Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_v3_module.xml @ 2956:a85e4d126bc7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>