Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_v3_module.xml @ 2956:a85e4d126bc7
Updated docs for the upcoming NGINX Plus release.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 02 May 2023 11:39:21 +0100 |
parents | |
children | cebca5ba84d7 |
comparison
equal
deleted
inserted
replaced
2955:2c4d7151b9a9 | 2956:a85e4d126bc7 |
---|---|
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_v3_module" | |
10 link="/en/docs/http/ngx_http_v3_module.html" | |
11 lang="en" | |
12 rev="1"> | |
13 | |
14 <section id="summary"> | |
15 | |
16 <para> | |
17 The <literal>ngx_http_v3_module</literal> module (1.23.4) provides | |
18 experimental support for | |
19 <link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link>. | |
20 </para> | |
21 | |
22 <para> | |
23 This module is not built by default, it should be enabled with the | |
24 <link doc="../configure.xml"><literal>--with-http_v3_module</literal></link> | |
25 configuration parameter. | |
26 <note> | |
27 An SSL library that provides QUIC support | |
28 such as | |
29 <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>, | |
30 <link url="https://www.libressl.org">LibreSSL</link>, or | |
31 <link url="https://github.com/quictls/openssl">QuicTLS</link> | |
32 is recommended to build and run this module. | |
33 Otherwise, | |
34 when using the <link url="https://openssl.org">OpenSSL</link> library, | |
35 OpenSSL compatibility layer will be used that does not support | |
36 <link doc="ngx_http_ssl_module.xml" id="ssl_early_data">early data</link>. | |
37 </note> | |
38 </para> | |
39 | |
40 | |
41 <para> | |
42 <note> | |
43 The module is available as | |
44 <literal>nginx-quic</literal> in | |
45 <link doc="../quic.xml" id="linux">prebult Linux packages</link>. | |
46 The module is also available as part of our | |
47 <commercial_version>commercial subscription</commercial_version> | |
48 in a separate <literal>nginx-plus-http3</literal> package. | |
49 </note> | |
50 </para> | |
51 | |
52 </section> | |
53 | |
54 | |
55 <section id="issues" name="Known Issues"> | |
56 | |
57 <para> | |
58 The module is experimental, caveat emptor applies. | |
59 </para> | |
60 | |
61 </section> | |
62 | |
63 | |
64 <section id="example" name="Example Configuration"> | |
65 | |
66 <para> | |
67 <example> | |
68 http { | |
69 log_format quic '$remote_addr - $remote_user [$time_local] ' | |
70 '"$request" $status $body_bytes_sent ' | |
71 '"$http_referer" "$http_user_agent" "$http3"'; | |
72 | |
73 access_log logs/access.log quic; | |
74 | |
75 server { | |
76 # for better compatibility it's recommended | |
77 # to use the same port for http/3 and https | |
78 listen 8443 quic reuseport; | |
79 listen 8443 ssl; | |
80 | |
81 ssl_certificate certs/example.com.crt; | |
82 ssl_certificate_key certs/example.com.key; | |
83 | |
84 location / { | |
85 # used to advertise the availability of HTTP/3 | |
86 add_header Alt-Svc 'h3=":8443"; ma=86400'; | |
87 } | |
88 } | |
89 } | |
90 </example> | |
91 Note that accepting HTTP/3 connections over TLS requires | |
92 the TLSv1.3 protocol support, which is available since | |
93 <link url="http://www.openssl.org">OpenSSL</link> version 1.1.1. | |
94 </para> | |
95 | |
96 </section> | |
97 | |
98 | |
99 <section id="directives" name="Directives"> | |
100 | |
101 <directive name="http3"> | |
102 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
103 <default>on</default> | |
104 <context>http</context> | |
105 <context>server</context> | |
106 | |
107 <para> | |
108 Enables | |
109 <link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link> | |
110 protocol negotiation. | |
111 </para> | |
112 | |
113 </directive> | |
114 | |
115 | |
116 <directive name="http3_hq"> | |
117 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
118 <default>off</default> | |
119 <context>http</context> | |
120 <context>server</context> | |
121 | |
122 <para> | |
123 Enables HTTP/0.9 protocol negotiation | |
124 used in | |
125 <link url="https://github.com/marten-seemann/quic-interop-runner">QUIC | |
126 interoperability tests</link>. | |
127 </para> | |
128 | |
129 </directive> | |
130 | |
131 | |
132 <directive name="http3_max_concurrent_pushes"> | |
133 <syntax><value>number</value></syntax> | |
134 <default>10</default> | |
135 <context>http</context> | |
136 <context>server</context> | |
137 | |
138 <para> | |
139 Limits the maximum number of concurrent | |
140 <link id="http3_push">push</link> requests in a connection. | |
141 </para> | |
142 | |
143 </directive> | |
144 | |
145 | |
146 <directive name="http3_max_concurrent_streams"> | |
147 <syntax><value>number</value></syntax> | |
148 <default>128</default> | |
149 <context>http</context> | |
150 <context>server</context> | |
151 | |
152 <para> | |
153 Sets the maximum number of concurrent HTTP/3 request streams | |
154 in a connection. | |
155 </para> | |
156 | |
157 </directive> | |
158 | |
159 | |
160 <directive name="http3_push"> | |
161 <syntax><value>uri</value> | <literal>off</literal></syntax> | |
162 <default>off</default> | |
163 <context>http</context> | |
164 <context>server</context> | |
165 <context>location</context> | |
166 | |
167 <para> | |
168 Pre-emptively sends | |
169 (<link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push">pushes</link>) | |
170 a request to the specified <value>uri</value> | |
171 along with the response to the original request. | |
172 Only relative URIs with absolute path will be processed, | |
173 for example: | |
174 <example> | |
175 http3_push /static/css/main.css; | |
176 </example> | |
177 The <value>uri</value> value can contain variables. | |
178 </para> | |
179 | |
180 <para> | |
181 Several <literal>http3_push</literal> directives | |
182 can be specified on the same configuration level. | |
183 The <literal>off</literal> parameter cancels the effect | |
184 of the <literal>http3_push</literal> directives | |
185 inherited from the previous configuration level. | |
186 </para> | |
187 | |
188 </directive> | |
189 | |
190 | |
191 <directive name="http3_push_preload"> | |
192 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
193 <default>off</default> | |
194 <context>http</context> | |
195 <context>server</context> | |
196 <context>location</context> | |
197 | |
198 <para> | |
199 Enables automatic conversion of | |
200 <link url="https://www.w3.org/TR/preload/#server-push-http-3">preload | |
201 links</link> | |
202 specified in the <header>Link</header> response header fields into | |
203 <link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push">push</link> | |
204 requests. | |
205 </para> | |
206 | |
207 </directive> | |
208 | |
209 | |
210 <directive name="http3_stream_buffer_size"> | |
211 <syntax><value>size</value></syntax> | |
212 <default>64k</default> | |
213 <context>http</context> | |
214 <context>server</context> | |
215 | |
216 <para> | |
217 Sets the size of the buffer used for reading and writing of the | |
218 QUIC streams. | |
219 </para> | |
220 | |
221 </directive> | |
222 | |
223 | |
224 <directive name="quic_active_connection_id_limit"> | |
225 <syntax><value>number</value></syntax> | |
226 <default>2</default> | |
227 <context>http</context> | |
228 <context>server</context> | |
229 | |
230 <para> | |
231 Sets the | |
232 QUIC <literal>active_connection_id_limit</literal> transport parameter value. | |
233 This is the maximum number of client connection IDs | |
234 which can be stored on the server. | |
235 </para> | |
236 | |
237 </directive> | |
238 | |
239 | |
240 <directive name="quic_bpf"> | |
241 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
242 <default>off</default> | |
243 <context>main</context> | |
244 | |
245 <para> | |
246 Enables routing of QUIC packets using | |
247 <link url="https://ebpf.io/">eBPF</link>. | |
248 When enabled, this allows supporting QUIC connection migration. | |
249 </para> | |
250 | |
251 <para> | |
252 <note> | |
253 The directive is only supported on Linux 5.7+. | |
254 </note> | |
255 </para> | |
256 | |
257 </directive> | |
258 | |
259 | |
260 <directive name="quic_gso"> | |
261 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
262 <default>off</default> | |
263 <context>http</context> | |
264 <context>server</context> | |
265 | |
266 <para> | |
267 Enables sending in optimized batch mode | |
268 using segmentation offloading. | |
269 </para> | |
270 | |
271 <para> | |
272 <note> | |
273 Optimized sending is supported only on Linux | |
274 featuring <literal>UDP_SEGMENT</literal>. | |
275 </note> | |
276 </para> | |
277 | |
278 </directive> | |
279 | |
280 | |
281 <directive name="quic_host_key"> | |
282 <syntax><value>file</value></syntax> | |
283 <default/> | |
284 <context>http</context> | |
285 <context>server</context> | |
286 | |
287 <para> | |
288 Sets a <value>file</value> with the secret key used to encrypt | |
289 stateless reset and address validation tokens. | |
290 By default, a random key is generated on each reload. | |
291 Tokens generated with old keys are not accepted. | |
292 </para> | |
293 | |
294 </directive> | |
295 | |
296 | |
297 <directive name="quic_mtu"> | |
298 <syntax><value>size</value></syntax> | |
299 <default>65527</default> | |
300 <context>http</context> | |
301 <context>server</context> | |
302 | |
303 <para> | |
304 Sets the | |
305 QUIC <literal>max_udp_payload_size</literal> transport parameter value. | |
306 This is the maximum UDP payload possible to receive. | |
307 </para> | |
308 | |
309 </directive> | |
310 | |
311 | |
312 <directive name="quic_retry"> | |
313 <syntax><literal>on</literal> | <literal>off</literal></syntax> | |
314 <default>off</default> | |
315 <context>http</context> | |
316 <context>server</context> | |
317 | |
318 <para> | |
319 Enables the | |
320 <link url="https://datatracker.ietf.org/doc/html/rfc9000#name-address-validation">QUIC | |
321 Address Validation</link> feature. | |
322 This includes sending a new token in a <literal>Retry</literal> packet | |
323 or a <literal>NEW_TOKEN</literal> frame | |
324 and | |
325 validating a token received in the <literal>Initial</literal> packet. | |
326 </para> | |
327 | |
328 </directive> | |
329 | |
330 </section> | |
331 | |
332 | |
333 <section id="variables" name="Embedded Variables"> | |
334 | |
335 <para> | |
336 The <literal>ngx_http_v3_module</literal> module | |
337 supports the following embedded variables: | |
338 <list type="tag" compact="no"> | |
339 | |
340 <tag-name id="var_http3"><var>$http3</var></tag-name> | |
341 <tag-desc> | |
342 negotiated protocol identifier: | |
343 “<literal>h3</literal>” for HTTP/3 connections, | |
344 “<literal>hq</literal>” for hq connections, | |
345 or an empty string otherwise. | |
346 </tag-desc> | |
347 | |
348 </list> | |
349 </para> | |
350 | |
351 </section> | |
352 | |
353 </module> |