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="allowSchemeMismatch" required="false">
       <p>A boolean value which can be used to enable or disable the consistency
       check for the scheme presented by the user agent in the HTTP/2 stream and
       the channel over which the stream was received. This should only be set to
       <code>true</code> where a trusted TLS terminating reverse proxy is used.
       If not specified, this attribute is set to <code>false</code>.</p>
     </attribute>

     <attribute name="discardRequestsAndResponses" required="false">
       <p>A boolean value which can be used to enable or disable the recycling
       of the container internal request and response processing objects. If set
       to <code>true</code> the request and response objects will be set for
       garbage collection after every request, otherwise they will be reused.
       If not specified, this attribute is set to <code>false</code>.</p>
     </attribute>

     <attribute name="drainTimeout" required="false">
       <p>Additional time in nanoseconds between sending the first graceful
       GOAWAY (max stream id) and the final GOAWAY (last seen stream id). During
       this time the server will continue to process new streams on the
       connection. This is to mitigate the race of client-buffered/sent packets
       for new streams and the final GOAWAY (with last seen stream id). By
       default, Tomcat uses the last computed RTT for this interval, but the RTT
       might have fluctuated due to network or server load conditions, or the
       client might have already buffered frames for opening new streams on a
       connection. If not specified, this attribute is set to <code>0</code>.</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>100</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="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="overheadContinuationThreshold" required="false">
       <p>The threshold below which the payload size of a non-final
       <code>CONTINUATION</code> frame will trigger an increase in the overhead
       count (see <strong>overheadCountFactor</strong>). The overhead count will
       be increased by <code>overheadContinuationThreshold/payloadSize</code> so
       that the smaller the <code>CONTINUATION</code> frame, the greater the
       increase in the overhead count. A value of zero or less disables the
       checking of non-final <code>CONTINUATION</code> frames. If not specified,
       a default value of <code>1024</code> will be used.</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 * overheadCountFactor</code>. The count is
       decreased by 20 for each data frame sent or received and each headers frame
       received. The count is increased by the <code>overheadCountFactor</code>
       for each setting, priority, priority update and ping frame 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
       approximately <code>20</code> or higher will close the connection before
       any streams can complete. If not specified, a default value of
       <code>10</code> will be used.</p>
     </attribute>

     <attribute name="overheadResetFactor" required="false">
       <p>The amount by which the overhead count (see
       <strong>overheadCountFactor</strong>) will be increased for each reset
       frame received or sent. If not specified, a default value of
       <code>50</code> will be used. A value of less than zero will be treated as
       zero.</p>
     </attribute>

     <attribute name="overheadDataThreshold" required="false">
       <p>The threshold below which the average payload size of the current and
       previous non-final <code>DATA</code> frames will trigger an increase in
       the overhead count (see <strong>overheadCountFactor</strong>). The
       overhead count will be increased by
       <code>overheadDataThreshold/average</code> so that the smaller the
       average, the greater the increase in the overhead count. A value of zero
       or less disables the checking of non-final <code>DATA</code> frames. If
       not specified, a default value of <code>1024</code> will be used.</p>
     </attribute>

     <attribute name="overheadWindowUpdateThreshold" required="false">
       <p>The threshold below which the average size of current and previous
       <code>WINDOW_UPDATE</code> frame will trigger an increase in the overhead
       count (see <strong>overheadCountFactor</strong>). The overhead count will
       be increased by <code>overheadWindowUpdateThreshold/average</code> so
       that the smaller the average, the greater the increase in the overhead
       count. A value of zero or less disables the checking of
       <code>WINDOW_UPDATE</code> frames. If not specified, a default value of
       <code>1024</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 connection 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>
       <p>This setting is ignored, and the sendfile capability disabled, if the
       <strong>useAsyncIO</strong> attribute of the associated
       <strong>Connector</strong> is set to <code>false</code>.</p>
       <p>The HTTP/2 sendfile capability uses <a
       href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/nio/MappedByteBuffer.html"
       >MappedByteBuffer</a> which is known to cause file locking on Windows.</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 attributes from
   the <a href="http.html">HTTP Connector</a> within which it is nested:</p>

   <ul>
     <li>allowedTrailerHeaders</li>
     <li>compressibleMimeType</li>
     <li>compression</li>
     <li>compressionMinSize</li>
     <li>maxCookieCount</li>
     <li>maxHttpHeaderSize</li>
     <li>maxHttpRequestHeaderSize</li>
     <li>maxParameterCount</li>
     <li>maxPartCount</li>
     <li>maxPartHeaderSize</li>
     <li>maxPostSize</li>
     <li>maxSavePostSize</li>
     <li>maxTrailerSize</li>
     <li>noCompressionUserAgents</li>
     <li>server</li>
     <li>serverRemoveAppProvidedValues</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="allowSchemeMismatch" required="false">
	<p>A boolean value which can be used to enable or disable the consistency
	check for the scheme presented by the user agent in the HTTP/2 stream and
	the channel over which the stream was received. This should only be set to
	<code>true</code> where a trusted TLS terminating reverse proxy is used.
	If not specified, this attribute is set to <code>false</code>.</p>
	</attribute>

	<attribute name="discardRequestsAndResponses" required="false">
	<p>A boolean value which can be used to enable or disable the recycling
	of the container internal request and response processing objects. If set
	to <code>true</code> the request and response objects will be set for
	garbage collection after every request, otherwise they will be reused.
	If not specified, this attribute is set to <code>false</code>.</p>
	</attribute>

	<attribute name="drainTimeout" required="false">
	<p>Additional time in nanoseconds between sending the first graceful
	GOAWAY (max stream id) and the final GOAWAY (last seen stream id). During
	this time the server will continue to process new streams on the
	connection. This is to mitigate the race of client-buffered/sent packets
	for new streams and the final GOAWAY (with last seen stream id). By
	default, Tomcat uses the last computed RTT for this interval, but the RTT
	might have fluctuated due to network or server load conditions, or the
	client might have already buffered frames for opening new streams on a
	connection. If not specified, this attribute is set to <code>0</code>.</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>100</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="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="overheadContinuationThreshold" required="false">
	<p>The threshold below which the payload size of a non-final
	<code>CONTINUATION</code> frame will trigger an increase in the overhead
	count (see <strong>overheadCountFactor</strong>). The overhead count will
	be increased by <code>overheadContinuationThreshold/payloadSize</code> so
	that the smaller the <code>CONTINUATION</code> frame, the greater the
	increase in the overhead count. A value of zero or less disables the
	checking of non-final <code>CONTINUATION</code> frames. If not specified,
	a default value of <code>1024</code> will be used.</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 * overheadCountFactor</code>. The count is
	decreased by 20 for each data frame sent or received and each headers frame
	received. The count is increased by the <code>overheadCountFactor</code>
	for each setting, priority, priority update and ping frame 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
	approximately <code>20</code> or higher will close the connection before
	any streams can complete. If not specified, a default value of
	<code>10</code> will be used.</p>
	</attribute>

	<attribute name="overheadResetFactor" required="false">
	<p>The amount by which the overhead count (see
	<strong>overheadCountFactor</strong>) will be increased for each reset
	frame received or sent. If not specified, a default value of
	<code>50</code> will be used. A value of less than zero will be treated as
	zero.</p>
	</attribute>

	<attribute name="overheadDataThreshold" required="false">
	<p>The threshold below which the average payload size of the current and
	previous non-final <code>DATA</code> frames will trigger an increase in
	the overhead count (see <strong>overheadCountFactor</strong>). The
	overhead count will be increased by
	<code>overheadDataThreshold/average</code> so that the smaller the
	average, the greater the increase in the overhead count. A value of zero
	or less disables the checking of non-final <code>DATA</code> frames. If
	not specified, a default value of <code>1024</code> will be used.</p>
	</attribute>

	<attribute name="overheadWindowUpdateThreshold" required="false">
	<p>The threshold below which the average size of current and previous
	<code>WINDOW_UPDATE</code> frame will trigger an increase in the overhead
	count (see <strong>overheadCountFactor</strong>). The overhead count will
	be increased by <code>overheadWindowUpdateThreshold/average</code> so
	that the smaller the average, the greater the increase in the overhead
	count. A value of zero or less disables the checking of
	<code>WINDOW_UPDATE</code> frames. If not specified, a default value of
	<code>1024</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 connection 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>
	<p>This setting is ignored, and the sendfile capability disabled, if the
	<strong>useAsyncIO</strong> attribute of the associated
	<strong>Connector</strong> is set to <code>false</code>.</p>
	<p>The HTTP/2 sendfile capability uses <a
	href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/nio/MappedByteBuffer.html"
	>MappedByteBuffer</a> which is known to cause file locking on Windows.</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 attributes from
	the <a href="http.html">HTTP Connector</a> within which it is nested:</p>

	<ul>
	<li>allowedTrailerHeaders</li>
	<li>compressibleMimeType</li>
	<li>compression</li>
	<li>compressionMinSize</li>
	<li>maxCookieCount</li>
	<li>maxHttpHeaderSize</li>
	<li>maxHttpRequestHeaderSize</li>
	<li>maxParameterCount</li>
	<li>maxPartCount</li>
	<li>maxPartHeaderSize</li>
	<li>maxPostSize</li>
	<li>maxSavePostSize</li>
	<li>maxTrailerSize</li>
	<li>noCompressionUserAgents</li>
	<li>server</li>
	<li>serverRemoveAppProvidedValues</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>