Mercurial > hg > nginx-quic

annotate README @ 9070:8347620e0e76 quic

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
README: revised TLSv1.3 requirement for QUIC. TLSv1.3 is enabled by default since d1cf09451ae8.
author Roman Arutyunyan <arut@nginx.com>
date Tue, 11 Apr 2023 18:29:20 +0400
parents c851a2ed5ce8
children b9230e37b8a1
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
1 Experimental QUIC support for nginx
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
2 -----------------------------------
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
3
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
4 1. Introduction
9024
93876a4c3b27 README: fixed toc.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9023
diff changeset
5 2. Building from sources
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
6 3. Configuration
9024
93876a4c3b27 README: fixed toc.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9023
diff changeset
7 4. Directives
93876a4c3b27 README: fixed toc.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9023
diff changeset
8 5. Clients
93876a4c3b27 README: fixed toc.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9023
diff changeset
9 6. Troubleshooting
93876a4c3b27 README: fixed toc.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9023
diff changeset
10 7. Contributing
93876a4c3b27 README: fixed toc.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9023
diff changeset
11 8. Links
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
12
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
13 1. Introduction
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
14
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
15 This is an experimental QUIC [1] / HTTP/3 [2] support for nginx.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
16
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
17 The code is developed in a separate "quic" branch available
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
18 at https://hg.nginx.org/nginx-quic. Currently it is based
8903
8d0753760546 Merged with the default branch.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8893
diff changeset
19 on nginx mainline 1.23.x. We merge new nginx releases into
8160
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8085
diff changeset
20 this branch regularly.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
21
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
22 The project code base is under the same BSD license as nginx.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
23
8929
98e94553ae51 README: updated the current status.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8903
diff changeset
24 The code is currently at a beta level of quality, however
98e94553ae51 README: updated the current status.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8903
diff changeset
25 there are several production deployments with it.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
26
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
27 NGINX Development Team is working on improving HTTP/3 support to
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
28 integrate it into the main NGINX codebase. Thus, expect further
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
29 updates of this code, including features, changes in behaviour,
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
30 bug fixes, and refactoring. NGINX Development team will be
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
31 grateful for any feedback and code submissions.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
32
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
33 Please contact NGINX Development Team via nginx-devel mailing list [3].
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
34
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
35 What works now:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
36
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
37 IETF QUIC version 1 is supported. Internet drafts are no longer supported.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
38
8160
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8085
diff changeset
39 nginx should be able to respond to HTTP/3 requests over QUIC and
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
40 it should be possible to upload and download big files without errors.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
41
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
42 + The handshake completes successfully
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
43 + One endpoint can update keys and its peer responds correctly
7867
70dbd7d0e466 Fixed a typo.
Vladimir Homutov <vl@nginx.com>
parents: 7866
diff changeset
44 + 0-RTT data is being received and acted on
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
45 + Connection is established using TLS Resume Ticket
7866
2b580ac17a47 README: Retry support, protocol error messages implemented.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7850
diff changeset
46 + A handshake that includes a Retry packet completes successfully
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
47 + Stream data is being exchanged and ACK'ed
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
48 + An H3 transaction succeeded
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
49 + One or both endpoints insert entries into dynamic table and
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
50 subsequently reference them from header blocks
8065
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8016
diff changeset
51 + Version Negotiation packet is sent to client with unknown version
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8016
diff changeset
52 + Lost packets are detected and retransmitted properly
8423
4117aa7fa38e QUIC: connection migration.
Vladimir Homutov <vl@nginx.com>
parents: 8407
diff changeset
53 + Clients may migrate to new address
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
54
9023
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
55 2. Building from sources
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
56
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
57 The build is configured using the configure command.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
58 Refer to http://nginx.org/en/docs/configure.html for details.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
59
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
60 When configuring nginx, it's possible to enable QUIC and HTTP/3
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
61 using the following new configuration options:
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
62
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
63 --with-http_v3_module - enable QUIC and HTTP/3
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
64 --with-stream_quic_module - enable QUIC in Stream
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
65
9046
7da4791e0264 QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents: 9024
diff changeset
66 A library that provides QUIC support is recommended to build nginx, there
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
67 are several of those available on the market:
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
68 + BoringSSL [4]
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
69 + LibreSSL [5]
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
70 + QuicTLS [6]
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
71
9046
7da4791e0264 QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents: 9024
diff changeset
72 Alternatively, nginx can be configured with OpenSSL compatibility
7da4791e0264 QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents: 9024
diff changeset
73 layer, which emulates BoringSSL QUIC API for OpenSSL. This mode is
7da4791e0264 QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents: 9024
diff changeset
74 enabled by default if native QUIC support is not detected.
7da4791e0264 QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents: 9024
diff changeset
75 0-RTT is not supported in OpenSSL compatibility mode.
7da4791e0264 QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents: 9024
diff changeset
76
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
77 Clone the NGINX QUIC repository
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
78
7850
796b5b6c43cd Mention quic branch in README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7849
diff changeset
79 $ hg clone -b quic https://hg.nginx.org/nginx-quic
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
80 $ cd nginx-quic
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
81
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
82 Use the following command to configure nginx with BoringSSL [4]
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
83
8792
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8718
diff changeset
84 $ ./auto/configure --with-debug --with-http_v3_module \
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8718
diff changeset
85 --with-cc-opt="-I../boringssl/include" \
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8718
diff changeset
86 --with-ld-opt="-L../boringssl/build/ssl \
7849
0e6528551f26 Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7843
diff changeset
87 -L../boringssl/build/crypto"
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
88 $ make
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
89
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
90 Alternatively, nginx can be configured with QuicTLS [6]
8792
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8718
diff changeset
91
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8718
diff changeset
92 $ ./auto/configure --with-debug --with-http_v3_module \
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8718
diff changeset
93 --with-cc-opt="-I../quictls/build/include" \
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8718
diff changeset
94 --with-ld-opt="-L../quictls/build/lib"
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8718
diff changeset
95
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
96 Alternatively, nginx can be configured with a modern version
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
97 of LibreSSL [7]
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
98
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
99 $ ./auto/configure --with-debug --with-http_v3_module \
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
100 --with-cc-opt="-I../libressl/build/include" \
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
101 --with-ld-opt="-L../libressl/build/lib"
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
102
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
103 3. Configuration
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
104
9047
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
105 The HTTP "listen" directive got a new option "quic" which enables
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
106 QUIC as client transport protocol instead of TCP.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
107
8005
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
diff changeset
108 The Stream "listen" directive got a new option "quic" which enables
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
diff changeset
109 QUIC as client transport protocol instead of TCP or plain UDP.
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
diff changeset
110
9047
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
111 Along with "quic", it's also possible to specify "reuseport"
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
112 option [8] to make it work properly with multiple workers.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
113
7879
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
114 To enable address validation:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
115
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
116 quic_retry on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
117
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
118 To enable 0-RTT:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
119
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
120 ssl_early_data on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
121
8544
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
122 To enable GSO (Generic Segmentation Offloading):
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
123
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
124 quic_gso on;
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
125
8893
0e74a77c2475 README: updated after HTTP/3 RFC publication, minor refinements.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8819
diff changeset
126 To limit maximum UDP payload size on receive path:
8713
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
127
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
128 quic_mtu <size>;
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
129
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
130 To set host key for various tokens:
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
131
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
132 quic_host_key <filename>;
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
133
9070
8347620e0e76 README: revised TLSv1.3 requirement for QUIC.
Roman Arutyunyan <arut@nginx.com>
parents: 9047
diff changeset
134 QUIC requires TLSv1.3 protocol, which is enabled by the default
8347620e0e76 README: revised TLSv1.3 requirement for QUIC.
Roman Arutyunyan <arut@nginx.com>
parents: 9047
diff changeset
135 by "ssl_protocols" directive.
8713
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
136
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
137 By default, GSO Linux-specific optimization [10] is disabled.
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
138 Enable it in case a corresponding network interface is configured to
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
139 support GSO.
8544
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
140
8016
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
141 A number of directives were added that configure HTTP/3:
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
142
9047
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
143 http3
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
144 http3_hq
8713
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
145 http3_stream_buffer_size
8016
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
146 http3_max_concurrent_pushes
8713
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
147 http3_max_concurrent_streams
8016
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
148 http3_push
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
149 http3_push_preload
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
150
8712
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8711
diff changeset
151 In http, an additional variable is available: $http3.
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8711
diff changeset
152 The value of $http3 is "h3" for HTTP/3 connections,
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8711
diff changeset
153 "hq" for hq connections, or an empty string otherwise.
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8711
diff changeset
154
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8711
diff changeset
155 In stream, an additional variable is available: $quic.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
156 The value of $quic is "quic" if QUIC connection is used,
8489
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8488
diff changeset
157 or an empty string otherwise.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
158
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
159 Example configuration:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
160
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
161 http {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
162 log_format quic '$remote_addr - $remote_user [$time_local] '
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
163 '"$request" $status $body_bytes_sent '
8718
44553428288d QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8713
diff changeset
164 '"$http_referer" "$http_user_agent" "$http3"';
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
165
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
166 access_log logs/access.log quic;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
167
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
168 server {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
169 # for better compatibility it's recommended
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
170 # to use the same port for quic and https
9047
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
171 listen 8443 quic reuseport;
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
172 listen 8443 ssl;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
173
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
174 ssl_certificate certs/example.com.crt;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
175 ssl_certificate_key certs/example.com.key;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
176
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
177 location / {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
178 # required for browsers to direct them into quic port
8489
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8488
diff changeset
179 add_header Alt-Svc 'h3=":8443"; ma=86400';
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
180 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
181 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
182 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
183
9023
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
184 4. Directives
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
185
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
186 Syntax: quic_bpf on | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
187 Default: quic_bpf off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
188 Context: main
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
189
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
190 Enables routing of QUIC packets using eBPF.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
191 When enabled, this allows to support QUIC connection migration.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
192 The directive is only supported on Linux 5.7+.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
193
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
194
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
195 Syntax: quic_retry on | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
196 Default: quic_retry off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
197 Context: http | stream, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
198
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
199 Enables the QUIC Address Validation feature. This includes:
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
200 - sending a new token in a Retry packet or a NEW_TOKEN frame
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
201 - validating a token received in the Initial packet
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
202
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
203
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
204 Syntax: quic_gso on | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
205 Default: quic_gso off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
206 Context: http | stream, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
207
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
208 Enables sending in optimized batch mode using segmentation offloading.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
209 Optimized sending is only supported on Linux featuring UDP_SEGMENT.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
210
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
211
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
212 Syntax: quic_mtu size;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
213 Default: quic_mtu 65527;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
214 Context: http | stream, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
215
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
216 Sets the QUIC max_udp_payload_size transport parameter value.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
217 This is the maximum UDP payload that we are willing to receive.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
218
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
219
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
220 Syntax: quic_host_key file;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
221 Default: -
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
222 Context: http | stream, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
223
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
224 Specifies a file with the secret key used to encrypt stateless reset and
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
225 address validation tokens. By default, a randomly generated key is used.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
226
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
227
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
228 Syntax: quic_active_connection_id_limit number;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
229 Default: quic_active_connection_id_limit 2;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
230 Context: http | stream, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
231
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
232 Sets the QUIC active_connection_id_limit transport parameter value.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
233 This is the maximum number of connection IDs we are willing to store.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
234
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
235
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
236 Syntax: quic_timeout time;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
237 Default: quic_timeout 60s;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
238 Context: stream, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
239
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
240 Defines a timeout used to negotiate the QUIC idle timeout.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
241 In the http module, it is taken from the keepalive_timeout directive.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
242
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
243
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
244 Syntax: quic_stream_buffer_size size;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
245 Default: quic_stream_buffer_size 64k;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
246 Context: stream, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
247
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
248 Syntax: http3_stream_buffer_size size;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
249 Default: http3_stream_buffer_size 64k;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
250 Context: http, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
251
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
252 Sets buffer size for reading and writing of the QUIC STREAM payload.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
253 The buffer size is used to calculate initial flow control limits
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
254 in the following QUIC transport parameters:
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
255 - initial_max_data
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
256 - initial_max_stream_data_bidi_local
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
257 - initial_max_stream_data_bidi_remote
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
258 - initial_max_stream_data_uni
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
259
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
260
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
261 Syntax: http3_max_concurrent_pushes number;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
262 Default: http3_max_concurrent_pushes 10;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
263 Context: http, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
264
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
265 Limits the maximum number of concurrent push requests in a connection.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
266
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
267
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
268 Syntax: http3_max_concurrent_streams number;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
269 Default: http3_max_concurrent_streams 128;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
270 Context: http, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
271
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
272 Sets the maximum number of concurrent HTTP/3 streams in a connection.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
273
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
274
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
275 Syntax: http3_push uri | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
276 Default: http3_push off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
277 Context: http, server, location
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
278
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
279 Pre-emptively sends (pushes) a request to the specified uri along with
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
280 the response to the original request. Only relative URIs with absolute
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
281 path will be processed, for example:
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
282
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
283 http3_push /static/css/main.css;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
284
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
285 The uri value can contain variables.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
286
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
287 Several http3_push directives can be specified on the same configuration
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
288 level. The off parameter cancels the effect of the http3_push directives
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
289 inherited from the previous configuration level.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
290
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
291
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
292 Syntax: http3_push_preload on | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
293 Default: http3_push_preload off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
294 Context: http, server, location
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
295
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
296 Enables automatic conversion of preload links specified in the “Link”
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
297 response header fields into push requests.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
298
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
299
9047
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
300 Syntax: http3 on | off;
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
301 Default: http3 on;
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
302 Context: http, server
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
303
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
304 Enables HTTP/3 protocol negotiation.
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
305
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
306
9023
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
307 Syntax: http3_hq on | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
308 Default: http3_hq off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
309 Context: http, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
310
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
311 Enables HTTP/0.9 protocol negotiation used in QUIC interoperability tests.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
312
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
313 5. Clients
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
314
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
315 * Browsers
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
316
8817
8f5d0ade0da7 README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8792
diff changeset
317 Known to work: Firefox 90+ and Chrome 92+ (QUIC version 1)
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
318
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
319 Beware of strange issues: sometimes browser may decide to ignore QUIC
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
320 Cache clearing/restart might help. Always check access.log and
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
321 error.log to make sure the browser is using HTTP/3 and not TCP https.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
322
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
323 * Console clients
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
324
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
325 Known to work: ngtcp2, firefox's neqo and chromium's console clients:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
326
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
327 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
328
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
329 $ ./neqo-client https://127.0.0.1:8443/
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
330
8817
8f5d0ade0da7 README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8792
diff changeset
331 $ chromium-build/out/my_build/quic_client http://example.com:8443
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
332
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
333
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
334 In case everyhing is right, the access log should show something like:
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
335
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
336 127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-"
8489
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8488
diff changeset
337 "nghttp3/ngtcp2 client" "quic"
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
338
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
339
9023
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
340 6. Troubleshooting
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
341
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
342 Here are some tips that may help to identify problems:
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
343
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
344 + Ensure nginx is built with proper SSL library that supports QUIC
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
345
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
346 + Ensure nginx is using the proper SSL library in runtime
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
347 (`nginx -V` shows what it's using)
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
348
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
349 + Ensure a client is actually sending requests over QUIC
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
350 (see "Clients" section about browsers and cache)
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
351
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
352 We recommend to start with simple console client like ngtcp2
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
353 to ensure the server is configured properly before trying
7872
578563babbd1 Fixed a typo.
Vladimir Homutov <vl@nginx.com>
parents: 7867
diff changeset
354 with real browsers that may be very picky with certificates,
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
355 for example.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
356
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
357 + Build nginx with debug support [9] and check the debug log.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
358 It should contain all details about connection and why it
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
359 failed. All related messages contain "quic " prefix and can
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
360 be easily filtered out.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
361
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
362 + For a deeper investigation, please enable additional debugging
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
363 in src/event/quic/ngx_event_quic_connection.h:
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
364
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
365 #define NGX_QUIC_DEBUG_PACKETS
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
366 #define NGX_QUIC_DEBUG_FRAMES
8241
2dfc5ef29973 QUIC: introduced QUIC buffers.
Roman Arutyunyan <arut@nginx.com>
parents: 8160
diff changeset
367 #define NGX_QUIC_DEBUG_ALLOC
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
368 #define NGX_QUIC_DEBUG_CRYPTO
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
369
9023
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
370 7. Contributing
7887
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 7879
diff changeset
371
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
372 Please refer to
7887
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 7879
diff changeset
373 http://nginx.org/en/docs/contributing_changes.html
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 7879
diff changeset
374
9023
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
375 8. Links
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
376
8488
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8423
diff changeset
377 [1] https://datatracker.ietf.org/doc/html/rfc9000
8893
0e74a77c2475 README: updated after HTTP/3 RFC publication, minor refinements.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8819
diff changeset
378 [2] https://datatracker.ietf.org/doc/html/rfc9114
9024
93876a4c3b27 README: fixed toc.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9023
diff changeset
379 [3] https://mailman.nginx.org/mailman/listinfo/nginx-devel
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
380 [4] https://boringssl.googlesource.com/boringssl/
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
381 [5] https://www.libressl.org/
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
382 [6] https://github.com/quictls/openssl
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
383 [7] https://github.com/libressl-portable/portable/releases/tag/v3.6.0
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
384 [8] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
385 [9] https://nginx.org/en/docs/debugging_log.html
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
386 [10] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf