mirror of
https://github.com/apache/httpd.git
synced 2025-08-01 16:41:19 +00:00
0e132fa7f3
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.17-protocols-http2@1701655 13f79535-47bb-0310-9956-ffa450edef68
279 lines
11 KiB
XML
279 lines
11 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
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.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_h2.xml.meta">
|
|
|
|
<name>mod_h2</name>
|
|
<description>Support for the HTTP/2 transport layer</description>
|
|
<status>Extension</status>
|
|
<sourcefile>mod_h2.c</sourcefile>
|
|
<identifier>h2_module</identifier>
|
|
|
|
<summary>
|
|
<p>This module provides HTTP/2 (RFC 7540) support for the Apache
|
|
HTTP Server.</p>
|
|
|
|
<p>This module relies on <a href="http://nghttp2.org/">libnghttp2</a>
|
|
to provide the core http/2 engine.</p>
|
|
|
|
</summary>
|
|
|
|
<directivesynopsis>
|
|
<name>H2Direct</name>
|
|
<description>H2 Direct Protocol Switch</description>
|
|
<syntax>H2Direct on|off</syntax>
|
|
<default>H2Direct on (for non TLS)</default>
|
|
<contextlist>
|
|
<context>server config</context>
|
|
<context>virtual host</context>
|
|
</contextlist>
|
|
|
|
<usage>
|
|
<p>
|
|
This directive toggles the usage of the HTTP/2 Direct Mode. This
|
|
should be used inside a
|
|
<directive module="core" type="section">VirtualHost</directive>
|
|
section to enable direct HTTP/2 communication for that virtual host.
|
|
Direct communication means that if the first bytes received by the
|
|
server on a connection match the HTTP/2 preamble, the HTTP/2
|
|
protocol is switched to immediately without further negotiation.
|
|
This mode falls outside the RFC 7540 but has become widely implemented
|
|
as it is very convenient for development and testing.
|
|
By default the direct HTTP/2 mode is enabled.
|
|
</p>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
H2Direct on
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>H2MaxSessionStreams</name>
|
|
<description>Maximum number of active streams per HTTP/2 session.</description>
|
|
<syntax>H2MaxSessionStreams <em>n</em></syntax>
|
|
<default>H2MaxSessionStreams 100</default>
|
|
<contextlist>
|
|
<context>server config</context>
|
|
<context>virtual host</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>
|
|
This directive sets the maximum number of active streams per HTTP/2 session (e.g. connection)
|
|
that the server allows. A stream is active if it is not <code>idle</code> or
|
|
<code>closed</code> according to RFC 7540.
|
|
</p>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
H2MaxSessionStreams 20
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>H2StreamMaxMemSize</name>
|
|
<description>Maximum amount of output data buffered per stream.</description>
|
|
<syntax>H2StreamMaxMemSize <em>bytes</em></syntax>
|
|
<default>H2StreamMaxMemSize 65536</default>
|
|
<contextlist>
|
|
<context>server config</context>
|
|
<context>virtual host</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>
|
|
This directive sets the maximum number of outgoing data bytes buffered in memory
|
|
for an active streams. This memory is not allocated per stream as such. Allocations
|
|
are counted against this limit when they are about to be done. Stream processing
|
|
freezes when the limit has been reached and will only continue when buffered data
|
|
has been sent out to the client.
|
|
</p>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
H2StreamMaxMemSize 128000
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>H2WindowSize</name>
|
|
<description>Size of Stream Window for upstream data.</description>
|
|
<syntax>H2WindowSize <em>bytes</em></syntax>
|
|
<default>H2WindowSize 65536</default>
|
|
<contextlist>
|
|
<context>server config</context>
|
|
<context>virtual host</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>
|
|
This directive sets the size of the window that is used for flow control
|
|
from client to server and limits the amount of data the server has to buffer.
|
|
The client will stop sending on a stream once the limit has been reached until
|
|
the server announces more available space (as it has processed some of the data).
|
|
</p><p>
|
|
This limit affects only request bodies, not its meta data such as headers. Also,
|
|
it has no effect on response bodies as the window size for those are managed
|
|
by the clients.
|
|
</p>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
H2WindowSize 128000
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>H2MinWorkers</name>
|
|
<description>Minimal number of worker threads to use per child process.</description>
|
|
<syntax>H2MinWorkers <em>n</em></syntax>
|
|
<contextlist>
|
|
<context>server config</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>
|
|
This directive sets the minimum number of worker threads to spawn
|
|
per child process for HTTP/2 processing. If this directive is not used,
|
|
<code>mod_h2</code> will chose a value suitable for the <code>mpm</code>
|
|
module loaded.
|
|
</p>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
H2MinWorkers 10
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>H2MaxWorkers</name>
|
|
<description>Maximum number of worker threads to use per child process.</description>
|
|
<syntax>H2MaxWorkers <em>n</em></syntax>
|
|
<contextlist>
|
|
<context>server config</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>
|
|
This directive sets the maximum number of worker threads to spawn
|
|
per child process for HTTP/2 processing. If this directive is not used,
|
|
<code>mod_h2</code> will chose a value suitable for the <code>mpm</code>
|
|
module loaded.
|
|
</p>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
H2MaxWorkers 20
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>H2MaxWorkerIdleSeconds</name>
|
|
<description>Maximum number of seconds h2 workers remain idle until shut down.</description>
|
|
<syntax>H2MaxWorkerIdleSeconds <em>n</em></syntax>
|
|
<default>H2MaxWorkerIdleSeconds 600</default>
|
|
<contextlist>
|
|
<context>server config</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>
|
|
This directive sets the maximum number of seconds a h2 worker may
|
|
idle until it shuts itself down. This only happens while the number of
|
|
h2 workers exceeds <code>H2MinWorkers</code>.
|
|
</p>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
H2MaxWorkerIdleSeconds 20
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>H2SessionExtraFiles</name>
|
|
<description>Number of Extra File Handles</description>
|
|
<syntax>H2SessionExtraFiles <em>n</em></syntax>
|
|
<default>H2SessionExtraFiles 5</default>
|
|
<contextlist>
|
|
<context>server config</context>
|
|
<context>virtual host</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>
|
|
This directive sets maximum number of <em>extra</em> file handles
|
|
a HTTP/2 session is allowed to use. A file handle is counted as
|
|
<em>extra</em> when it is transfered from a h2 worker thread to
|
|
the main HTTP/2 connection handling. This commonly happens when
|
|
serving static files.
|
|
</p><p>
|
|
Depending on the processing model configured on the server, the
|
|
number of connections times number of active streams may exceed
|
|
the number of file handles for the process. On the other hand,
|
|
converting every file into memory bytes early results in too
|
|
many buffer writes. This option helps to mitigate that.
|
|
</p><p>
|
|
The number of file handles used by a server process is then in
|
|
the order of:
|
|
</p>
|
|
<pre>
|
|
(h2_connections * extra_files) + (h2_max_worker)
|
|
</pre>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
H2SessionExtraFiles 10
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>H2SerializeHeaders</name>
|
|
<description>Serialize Request/Resoonse Processing Switch</description>
|
|
<syntax>H2SerializeHeaders on|off</syntax>
|
|
<default>H2SerializeHeaders off</default>
|
|
<contextlist>
|
|
<context>server config</context>
|
|
<context>virtual host</context>
|
|
</contextlist>
|
|
<usage>
|
|
<p>
|
|
This directive toggles if HTTP/2 requests shall be serialized in
|
|
HTTP/1.1 format for processing by <code>httpd</code> core or if
|
|
received binary data shall be passed into the <code>request_rec</code>s
|
|
directly.
|
|
</p>
|
|
<p>
|
|
Serialization will lower performance, but gives more backward
|
|
compatibility in case custom filters/hooks need it.
|
|
</p>
|
|
<example><title>Example</title>
|
|
<highlight language="config">
|
|
H2SerializeHeaders on
|
|
</highlight>
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
</modulesynopsis>
|