Mercurial > hg > nginx-quic

annotate README @ 9069:9ea62b6250f2 quic

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Stream: allow waiting on a blocked QUIC stream (ticket #2479). Previously, waiting on a shared connection was not allowed, because the only type of such connection was plain UDP. However, QUIC stream connections are also shared since they share socket descriptor with the listen connection. Meanwhile, it's perfectly normal to wait on such connections. The issue manifested itself with stream write errors when the amount of data exceeded stream buffer size or flow control. Now no error is triggered and Stream write module is allowed to wait for buffer space to become available.
author Roman Arutyunyan <arut@nginx.com>
date Thu, 06 Apr 2023 15:39:48 +0400
parents c851a2ed5ce8
children 8347620e0e76
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
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
122 Make sure that TLS 1.3 is configured which is required for QUIC:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
123
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
124 ssl_protocols TLSv1.3;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
125
8544
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
126 To enable GSO (Generic Segmentation Offloading):
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
127
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
128 quic_gso on;
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
129
8893
0e74a77c2475 README: updated after HTTP/3 RFC publication, minor refinements.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8819
diff changeset
130 To limit maximum UDP payload size on receive path:
8713
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_mtu <size>;
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
133
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
134 To set host key for various tokens:
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
135
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
136 quic_host_key <filename>;
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
137
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
138
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
139 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
140 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
141 support GSO.
8544
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
142
8016
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
143 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
144
9047
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
145 http3
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
146 http3_hq
8713
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
147 http3_stream_buffer_size
8016
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
148 http3_max_concurrent_pushes
8713
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8712
diff changeset
149 http3_max_concurrent_streams
8016
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
150 http3_push
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
151 http3_push_preload
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
152
8712
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8711
diff changeset
153 In http, an additional variable is available: $http3.
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8711
diff changeset
154 The value of $http3 is "h3" for HTTP/3 connections,
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8711
diff changeset
155 "hq" for hq connections, or an empty string otherwise.
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8711
diff changeset
156
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8711
diff changeset
157 In stream, an additional variable is available: $quic.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
158 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
159 or an empty string otherwise.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
160
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
161 Example configuration:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
162
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
163 http {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
164 log_format quic '$remote_addr - $remote_user [$time_local] '
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
165 '"$request" $status $body_bytes_sent '
8718
44553428288d QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8713
diff changeset
166 '"$http_referer" "$http_user_agent" "$http3"';
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
167
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
168 access_log logs/access.log quic;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
169
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
170 server {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
171 # for better compatibility it's recommended
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
172 # 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
173 listen 8443 quic reuseport;
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
174 listen 8443 ssl;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
175
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
176 ssl_certificate certs/example.com.crt;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
177 ssl_certificate_key certs/example.com.key;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
178 ssl_protocols TLSv1.3;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
179
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
180 location / {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
181 # 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
182 add_header Alt-Svc 'h3=":8443"; ma=86400';
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
183 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
184 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
185 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
186
9023
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
187 4. Directives
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
188
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
189 Syntax: quic_bpf on | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
190 Default: quic_bpf off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
191 Context: main
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
192
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
193 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
194 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
195 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
196
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
197
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
198 Syntax: quic_retry on | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
199 Default: quic_retry off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
200 Context: http | stream, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
201
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
202 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
203 - 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
204 - 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
205
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
206
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
207 Syntax: quic_gso on | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
208 Default: quic_gso off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
209 Context: http | stream, server
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 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
212 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
213
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
214
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
215 Syntax: quic_mtu size;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
216 Default: quic_mtu 65527;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
217 Context: http | stream, server
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 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
220 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
221
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
222
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
223 Syntax: quic_host_key file;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
224 Default: -
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
225 Context: http | stream, server
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 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
228 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
229
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
230
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
231 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
232 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
233 Context: http | stream, server
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 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
236 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
237
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
238
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
239 Syntax: quic_timeout time;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
240 Default: quic_timeout 60s;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
241 Context: stream, server
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 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
244 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
245
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
246
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
247 Syntax: quic_stream_buffer_size size;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
248 Default: quic_stream_buffer_size 64k;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
249 Context: stream, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
250
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
251 Syntax: http3_stream_buffer_size size;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
252 Default: http3_stream_buffer_size 64k;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
253 Context: http, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
254
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
255 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
256 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
257 in the following QUIC transport parameters:
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
258 - initial_max_data
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
259 - initial_max_stream_data_bidi_local
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
260 - initial_max_stream_data_bidi_remote
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
261 - initial_max_stream_data_uni
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
262
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
263
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
264 Syntax: http3_max_concurrent_pushes number;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
265 Default: http3_max_concurrent_pushes 10;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
266 Context: http, server
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 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
269
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
270
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
271 Syntax: http3_max_concurrent_streams number;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
272 Default: http3_max_concurrent_streams 128;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
273 Context: http, server
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 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
276
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
277
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
278 Syntax: http3_push uri | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
279 Default: http3_push off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
280 Context: http, server, location
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
281
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
282 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
283 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
284 path will be processed, for example:
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
285
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
286 http3_push /static/css/main.css;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
287
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
288 The uri value can contain variables.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
289
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
290 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
291 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
292 inherited from the previous configuration level.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
293
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
294
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
295 Syntax: http3_push_preload on | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
296 Default: http3_push_preload off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
297 Context: http, server, location
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 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
300 response header fields into push requests.
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
301
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
302
9047
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
303 Syntax: http3 on | off;
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
304 Default: http3 on;
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
305 Context: http, server
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
306
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
307 Enables HTTP/3 protocol negotiation.
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
308
c851a2ed5ce8 HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents: 9046
diff changeset
309
9023
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
310 Syntax: http3_hq on | off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
311 Default: http3_hq off;
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
312 Context: http, server
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
313
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
314 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
315
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
316 5. Clients
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
317
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
318 * Browsers
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
319
8817
8f5d0ade0da7 README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8792
diff changeset
320 Known to work: Firefox 90+ and Chrome 92+ (QUIC version 1)
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
321
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
322 Beware of strange issues: sometimes browser may decide to ignore QUIC
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
323 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
324 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
325
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
326 * Console clients
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
327
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
328 Known to work: ngtcp2, firefox's neqo and chromium's console clients:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
329
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
330 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
331
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
332 $ ./neqo-client https://127.0.0.1:8443/
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
333
8817
8f5d0ade0da7 README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8792
diff changeset
334 $ chromium-build/out/my_build/quic_client http://example.com:8443
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
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
337 In case everyhing is right, the access log should show something like:
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 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
340 "nghttp3/ngtcp2 client" "quic"
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
341
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
342
9023
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
343 6. Troubleshooting
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
344
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
345 Here are some tips that may help to identify problems:
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
346
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
347 + Ensure nginx is built with proper SSL library that supports QUIC
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 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
350 (`nginx -V` shows what it's using)
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
351
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
352 + Ensure a client is actually sending requests over QUIC
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
353 (see "Clients" section about browsers and cache)
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
354
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
355 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
356 to ensure the server is configured properly before trying
7872
578563babbd1 Fixed a typo.
Vladimir Homutov <vl@nginx.com>
parents: 7867
diff changeset
357 with real browsers that may be very picky with certificates,
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
358 for example.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
359
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
360 + Build nginx with debug support [9] and check the debug log.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
361 It should contain all details about connection and why it
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
362 failed. All related messages contain "quic " prefix and can
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
363 be easily filtered out.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
364
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
365 + 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
366 in src/event/quic/ngx_event_quic_connection.h:
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
367
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
368 #define NGX_QUIC_DEBUG_PACKETS
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
369 #define NGX_QUIC_DEBUG_FRAMES
8241
2dfc5ef29973 QUIC: introduced QUIC buffers.
Roman Arutyunyan <arut@nginx.com>
parents: 8160
diff changeset
370 #define NGX_QUIC_DEBUG_ALLOC
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
371 #define NGX_QUIC_DEBUG_CRYPTO
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
372
9023
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
373 7. Contributing
7887
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 7879
diff changeset
374
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
375 Please refer to
7887
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 7879
diff changeset
376 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
377
9023
3c33d39a51d3 README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8956
diff changeset
378 8. Links
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
379
8488
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8423
diff changeset
380 [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
381 [2] https://datatracker.ietf.org/doc/html/rfc9114
9024
93876a4c3b27 README: fixed toc.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9023
diff changeset
382 [3] https://mailman.nginx.org/mailman/listinfo/nginx-devel
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
383 [4] https://boringssl.googlesource.com/boringssl/
8956
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
384 [5] https://www.libressl.org/
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
385 [6] https://github.com/quictls/openssl
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
386 [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
387 [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
388 [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
389 [10] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf