Mercurial > hg > nginx-site
annotate xml/en/docs/http/ngx_http_v2_module.xml @ 1759:42d2806f5b28
Updated example in ngx_stream_split_clients_module with variables.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Wed, 03 Aug 2016 14:20:50 +0300 |
parents | ea60a7dff3c1 |
children | 1d0811707e09 |
rev | line source |
---|---|
1566 | 1 <?xml version="1.0"?> |
2 | |
3 <!-- | |
4 Copyright (C) Nginx, Inc. | |
5 --> | |
6 | |
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> | |
8 | |
9 <module name="Module ngx_http_v2_module" | |
10 link="/en/docs/http/ngx_http_v2_module.html" | |
11 lang="en" | |
1707
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
12 rev="7"> |
1566 | 13 |
14 <section id="summary"> | |
15 | |
16 <para> | |
17 The <literal>ngx_http_v2_module</literal> module (1.9.5) provides | |
18 support for <link url="https://tools.ietf.org/html/rfc7540">HTTP/2</link> | |
19 and supersedes the | |
20 <link doc="ngx_http_spdy_module.xml">ngx_http_spdy_module</link> module. | |
21 </para> | |
22 | |
23 <para> | |
24 This module is not built by default, it should be enabled with | |
25 the <literal>--with-http_v2_module</literal> | |
26 configuration parameter. | |
27 </para> | |
28 | |
29 </section> | |
30 | |
31 | |
1580
c711a8a1a8f9
Changed ID from "bugs" to "issues" for http/2, perl, spdy.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1577
diff
changeset
|
32 <section id="issues" name="Known Issues"> |
1577
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
33 |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
34 <para> |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
35 The module is experimental, caveat emptor applies. |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
36 </para> |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
37 |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
38 <para> |
1671
5154b356a1b2
Unbuffered request body upload support in http2.
Ruslan Ermilov <ru@nginx.com>
parents:
1666
diff
changeset
|
39 Before version 1.9.14, |
5154b356a1b2
Unbuffered request body upload support in http2.
Ruslan Ermilov <ru@nginx.com>
parents:
1666
diff
changeset
|
40 buffering of a client request body could not be disabled |
1577
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
41 regardless of |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
42 <link doc="ngx_http_proxy_module.xml" id="proxy_request_buffering"/>, |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
43 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_request_buffering"/>, |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
44 <link doc="ngx_http_uwsgi_module.xml" id="uwsgi_request_buffering"/>, and |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
45 <link doc="ngx_http_scgi_module.xml" id="scgi_request_buffering"/> |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
46 directive values. |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
47 </para> |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
48 |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
49 </section> |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
50 |
37be36b01d28
Added the "Known issues" section to the ngx_http_v2 module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1568
diff
changeset
|
51 |
1566 | 52 <section id="example" name="Example Configuration"> |
53 | |
54 <para> | |
55 <example> | |
56 server { | |
57 listen 443 ssl http2; | |
58 | |
59 ssl_certificate server.crt; | |
60 ssl_certificate_key server.key; | |
61 } | |
62 </example> | |
1568
61a3285d77aa
Paraphrased the ALPN/NPN requirements note so it makes sense.
Ruslan Ermilov <ru@nginx.com>
parents:
1566
diff
changeset
|
63 Note that accepting HTTP/2 connections over TLS requires |
1566 | 64 the “Application-Layer Protocol Negotiation” (ALPN) TLS extension |
1568
61a3285d77aa
Paraphrased the ALPN/NPN requirements note so it makes sense.
Ruslan Ermilov <ru@nginx.com>
parents:
1566
diff
changeset
|
65 support, which is available only since |
61a3285d77aa
Paraphrased the ALPN/NPN requirements note so it makes sense.
Ruslan Ermilov <ru@nginx.com>
parents:
1566
diff
changeset
|
66 <link url="http://www.openssl.org">OpenSSL</link> version 1.0.2. |
61a3285d77aa
Paraphrased the ALPN/NPN requirements note so it makes sense.
Ruslan Ermilov <ru@nginx.com>
parents:
1566
diff
changeset
|
67 Using the “Next Protocol Negotiation” (NPN) TLS extension for this purpose |
61a3285d77aa
Paraphrased the ALPN/NPN requirements note so it makes sense.
Ruslan Ermilov <ru@nginx.com>
parents:
1566
diff
changeset
|
68 (available since OpenSSL version 1.0.1) is not guaranteed. |
1566 | 69 </para> |
70 | |
1609
887ce78207ac
Added note about ssl_prefer_server_ciphers in HTTP/2.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1596
diff
changeset
|
71 <para> |
887ce78207ac
Added note about ssl_prefer_server_ciphers in HTTP/2.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1596
diff
changeset
|
72 Also note that if the |
887ce78207ac
Added note about ssl_prefer_server_ciphers in HTTP/2.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1596
diff
changeset
|
73 <link doc="ngx_http_ssl_module.xml" id="ssl_prefer_server_ciphers"/> directive |
1659
680cbf783efe
Fixed some misuses of "value".
Ruslan Ermilov <ru@nginx.com>
parents:
1636
diff
changeset
|
74 is set to the value “<literal>on</literal>”, |
1609
887ce78207ac
Added note about ssl_prefer_server_ciphers in HTTP/2.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1596
diff
changeset
|
75 the <link doc="ngx_http_ssl_module.xml" id="ssl_ciphers">ciphers</link> |
887ce78207ac
Added note about ssl_prefer_server_ciphers in HTTP/2.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1596
diff
changeset
|
76 should be configured to comply with |
887ce78207ac
Added note about ssl_prefer_server_ciphers in HTTP/2.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1596
diff
changeset
|
77 <link url="https://tools.ietf.org/html/rfc7540#appendix-A">RFC 7540, Appendix A</link> |
887ce78207ac
Added note about ssl_prefer_server_ciphers in HTTP/2.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1596
diff
changeset
|
78 black list and supported by clients. |
887ce78207ac
Added note about ssl_prefer_server_ciphers in HTTP/2.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1596
diff
changeset
|
79 </para> |
887ce78207ac
Added note about ssl_prefer_server_ciphers in HTTP/2.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1596
diff
changeset
|
80 |
1566 | 81 </section> |
82 | |
83 | |
84 <section id="directives" name="Directives"> | |
85 | |
86 <directive name="http2_chunk_size"> | |
87 <syntax><value>size</value></syntax> | |
88 <default>8k</default> | |
89 <context>http</context> | |
90 <context>server</context> | |
91 <context>location</context> | |
92 | |
93 <para> | |
94 Sets the maximum size of chunks | |
95 into which the response body is sliced. | |
96 A too low value results in higher overhead. | |
97 A too high value impairs prioritization due to | |
98 <link url="http://en.wikipedia.org/wiki/Head-of-line_blocking"> | |
99 HOL blocking</link>. | |
100 </para> | |
101 | |
102 </directive> | |
103 | |
104 | |
1707
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
105 <directive name="http2_body_preread_size"> |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
106 <syntax><value>size</value></syntax> |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
107 <default>64k</default> |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
108 <context>http</context> |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
109 <context>server</context> |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
110 <appeared-in>1.11.0</appeared-in> |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
111 |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
112 <para> |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
113 Sets the <value>size</value> of the buffer per each request |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
114 in which the request body may be saved |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
115 before it is started to be processed. |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
116 </para> |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
117 |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
118 </directive> |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
119 |
ea60a7dff3c1
Documented the http2_body_preread_size directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1671
diff
changeset
|
120 |
1566 | 121 <directive name="http2_idle_timeout"> |
122 <syntax><value>time</value></syntax> | |
123 <default>3m</default> | |
124 <context>http</context> | |
125 <context>server</context> | |
126 | |
127 <para> | |
128 Sets the timeout of inactivity after which the connection is closed. | |
129 </para> | |
130 | |
131 </directive> | |
132 | |
133 | |
134 <directive name="http2_max_concurrent_streams"> | |
135 <syntax><value>number</value></syntax> | |
136 <default>128</default> | |
137 <context>http</context> | |
138 <context>server</context> | |
139 | |
140 <para> | |
141 Sets the maximum number of concurrent HTTP/2 streams | |
142 in a connection. | |
143 </para> | |
144 | |
145 </directive> | |
146 | |
147 | |
1596
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
148 <directive name="http2_max_field_size"> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
149 <syntax><value>size</value></syntax> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
150 <default>4k</default> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
151 <context>http</context> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
152 <context>server</context> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
153 |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
154 <para> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
155 Limits the maximum size of |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
156 an <link url="http://tools.ietf.org/html/rfc7541">HPACK</link>-compressed |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
157 request header field. |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
158 The limit applies equally to both name and value. |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
159 Note that if Huffman encoding is applied, |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
160 the actual size of decompressed name and value strings may be larger. |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
161 For most requests, the default limit should be enough. |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
162 </para> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
163 |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
164 </directive> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
165 |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
166 |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
167 <directive name="http2_max_header_size"> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
168 <syntax><value>size</value></syntax> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
169 <default>16k</default> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
170 <context>http</context> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
171 <context>server</context> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
172 |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
173 <para> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
174 Limits the maximum size of the entire request header list after |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
175 <link url="http://tools.ietf.org/html/rfc7541">HPACK</link> decompression. |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
176 For most requests, the default limit should be enough. |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
177 </para> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
178 |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
179 </directive> |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
180 |
e491c669220e
Documented http2_max_field_size, http2_max_header_size
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1580
diff
changeset
|
181 |
1566 | 182 <directive name="http2_recv_buffer_size"> |
183 <syntax><value>size</value></syntax> | |
184 <default>256k</default> | |
185 <context>http</context> | |
186 | |
187 <para> | |
1666
08f48ecb13ba
Added a hyperlink to http2_recv_buffer_size.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1659
diff
changeset
|
188 Sets the size of the per |
08f48ecb13ba
Added a hyperlink to http2_recv_buffer_size.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1659
diff
changeset
|
189 <link doc="../ngx_core_module.xml" id="worker_processes">worker</link> |
08f48ecb13ba
Added a hyperlink to http2_recv_buffer_size.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
1659
diff
changeset
|
190 input buffer. |
1566 | 191 </para> |
192 | |
193 </directive> | |
194 | |
195 | |
196 <directive name="http2_recv_timeout"> | |
197 <syntax><value>time</value></syntax> | |
198 <default>30s</default> | |
199 <context>http</context> | |
200 <context>server</context> | |
201 | |
202 <para> | |
203 Sets the timeout for expecting more data from the client, | |
204 after which the connection is closed. | |
205 </para> | |
206 | |
207 </directive> | |
208 | |
209 </section> | |
210 | |
211 | |
212 <section id="variables" name="Embedded Variables"> | |
213 | |
214 <para> | |
215 The <literal>ngx_http_v2_module</literal> module | |
216 supports the following embedded variables: | |
217 <list type="tag" compact="no"> | |
218 | |
219 <tag-name id="var_http2"><var>$http2</var></tag-name> | |
220 <tag-desc> | |
221 negotiated protocol identifier: | |
222 “<literal>h2</literal>” for HTTP/2 over TLS, | |
223 “<literal>h2c</literal>” for HTTP/2 over cleartext TCP, | |
224 or an empty string otherwise. | |
225 </tag-desc> | |
226 | |
227 </list> | |
228 </para> | |
229 | |
230 </section> | |
231 | |
232 </module> |