Mercurial > hg > nginx-quic
annotate README @ 8960:6cf8ed15fd00 quic
Set default listen socket type in http.
The type field was added in 7999d3fbb765 at early stages of QUIC implementation
and was not initialized for default listen. Missing initialization resulted in
default listen socket creation error.
author | Roman Arutyunyan <arut@nginx.com> |
---|---|
date | Tue, 01 Nov 2022 17:00:35 +0400 |
parents | 79cd6993a3e3 |
children | 3c33d39a51d3 |
rev | line source |
---|---|
7843 | 1 Experimental QUIC support for nginx |
2 ----------------------------------- | |
3 | |
4 1. Introduction | |
5 2. Installing | |
6 3. Configuration | |
7 4. Clients | |
8 5. Troubleshooting | |
7887
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
7879
diff
changeset
|
9 6. Contributing |
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
7879
diff
changeset
|
10 7. Links |
7843 | 11 |
12 1. Introduction | |
13 | |
14 This is an experimental QUIC [1] / HTTP/3 [2] support for nginx. | |
15 | |
16 The code is developed in a separate "quic" branch available | |
17 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
|
18 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
|
19 this branch regularly. |
7843 | 20 |
21 The project code base is under the same BSD license as nginx. | |
22 | |
8929
98e94553ae51
README: updated the current status.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8903
diff
changeset
|
23 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
|
24 there are several production deployments with it. |
7843 | 25 |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
26 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
|
27 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
|
28 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
|
29 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
|
30 grateful for any feedback and code submissions. |
7843 | 31 |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
32 Please contact NGINX Development Team via nginx-devel mailing list [3]. |
7843 | 33 |
34 What works now: | |
35 | |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
36 IETF QUIC version 1 is supported. Internet drafts are no longer supported. |
7843 | 37 |
8160
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8085
diff
changeset
|
38 nginx should be able to respond to HTTP/3 requests over QUIC and |
7843 | 39 it should be possible to upload and download big files without errors. |
40 | |
41 + The handshake completes successfully | |
42 + One endpoint can update keys and its peer responds correctly | |
7867 | 43 + 0-RTT data is being received and acted on |
7843 | 44 + 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
|
45 + A handshake that includes a Retry packet completes successfully |
7843 | 46 + Stream data is being exchanged and ACK'ed |
47 + An H3 transaction succeeded | |
48 + One or both endpoints insert entries into dynamic table and | |
49 subsequently reference them from header blocks | |
8065 | 50 + Version Negotiation packet is sent to client with unknown version |
51 + Lost packets are detected and retransmitted properly | |
8423
4117aa7fa38e
QUIC: connection migration.
Vladimir Homutov <vl@nginx.com>
parents:
8407
diff
changeset
|
52 + Clients may migrate to new address |
7843 | 53 |
54 2. Installing | |
55 | |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
56 A library that provides QUIC support is required to build nginx, there |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
57 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
|
58 + BoringSSL [4] |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
59 + LibreSSL [5] |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
60 + QuicTLS [6] |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
61 |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
62 Clone the NGINX QUIC repository |
7843 | 63 |
7850
796b5b6c43cd
Mention quic branch in README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7849
diff
changeset
|
64 $ hg clone -b quic https://hg.nginx.org/nginx-quic |
7843 | 65 $ cd nginx-quic |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
66 |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
67 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
|
68 |
8792
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8718
diff
changeset
|
69 $ ./auto/configure --with-debug --with-http_v3_module \ |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8718
diff
changeset
|
70 --with-cc-opt="-I../boringssl/include" \ |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8718
diff
changeset
|
71 --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
|
72 -L../boringssl/build/crypto" |
7843 | 73 $ make |
74 | |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
75 Alternatively, nginx can be configured with QuicTLS [6] |
8792
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8718
diff
changeset
|
76 |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8718
diff
changeset
|
77 $ ./auto/configure --with-debug --with-http_v3_module \ |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8718
diff
changeset
|
78 --with-cc-opt="-I../quictls/build/include" \ |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8718
diff
changeset
|
79 --with-ld-opt="-L../quictls/build/lib" |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8718
diff
changeset
|
80 |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
81 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
|
82 of LibreSSL [7] |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
83 |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
84 $ ./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
|
85 --with-cc-opt="-I../libressl/build/include" \ |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
86 --with-ld-opt="-L../libressl/build/lib" |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
87 |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
88 When configuring nginx, it's possible to enable QUIC and HTTP/3 |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
89 using the following new configuration options: |
8005
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
7944
diff
changeset
|
90 |
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
7944
diff
changeset
|
91 --with-http_v3_module - enable QUIC and HTTP/3 |
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
7944
diff
changeset
|
92 --with-stream_quic_module - enable QUIC in Stream |
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
7944
diff
changeset
|
93 |
7843 | 94 3. Configuration |
95 | |
8711
be08b858086a
HTTP/3: http3_hq directive and NGX_HTTP_V3_HQ macro.
Roman Arutyunyan <arut@nginx.com>
parents:
8595
diff
changeset
|
96 The HTTP "listen" directive got a new option "http3" which enables |
be08b858086a
HTTP/3: http3_hq directive and NGX_HTTP_V3_HQ macro.
Roman Arutyunyan <arut@nginx.com>
parents:
8595
diff
changeset
|
97 HTTP/3 over QUIC on the specified port. |
7843 | 98 |
8005
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
7944
diff
changeset
|
99 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
|
100 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
|
101 |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
102 Along with "http3" or "quic", it's also possible to specify "reuseport" |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
103 option [8] to make it work properly with multiple workers. |
7843 | 104 |
7879
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7873
diff
changeset
|
105 To enable address validation: |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7873
diff
changeset
|
106 |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7873
diff
changeset
|
107 quic_retry on; |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7873
diff
changeset
|
108 |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7873
diff
changeset
|
109 To enable 0-RTT: |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7873
diff
changeset
|
110 |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7873
diff
changeset
|
111 ssl_early_data on; |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7873
diff
changeset
|
112 |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7873
diff
changeset
|
113 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
|
114 |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7873
diff
changeset
|
115 ssl_protocols TLSv1.3; |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7873
diff
changeset
|
116 |
8544
d0ef43a53a51
QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents:
8505
diff
changeset
|
117 To enable GSO (Generic Segmentation Offloading): |
d0ef43a53a51
QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents:
8505
diff
changeset
|
118 |
d0ef43a53a51
QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents:
8505
diff
changeset
|
119 quic_gso on; |
d0ef43a53a51
QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents:
8505
diff
changeset
|
120 |
8893
0e74a77c2475
README: updated after HTTP/3 RFC publication, minor refinements.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8819
diff
changeset
|
121 To limit maximum UDP payload size on receive path: |
8713
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8712
diff
changeset
|
122 |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8712
diff
changeset
|
123 quic_mtu <size>; |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8712
diff
changeset
|
124 |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8712
diff
changeset
|
125 To set host key for various tokens: |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8712
diff
changeset
|
126 |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8712
diff
changeset
|
127 quic_host_key <filename>; |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8712
diff
changeset
|
128 |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8712
diff
changeset
|
129 |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
130 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
|
131 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
|
132 support GSO. |
8544
d0ef43a53a51
QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents:
8505
diff
changeset
|
133 |
8016
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8005
diff
changeset
|
134 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
|
135 |
8713
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8712
diff
changeset
|
136 http3_stream_buffer_size |
8016
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8005
diff
changeset
|
137 http3_max_concurrent_pushes |
8713
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8712
diff
changeset
|
138 http3_max_concurrent_streams |
8016
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8005
diff
changeset
|
139 http3_push |
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8005
diff
changeset
|
140 http3_push_preload |
8711
be08b858086a
HTTP/3: http3_hq directive and NGX_HTTP_V3_HQ macro.
Roman Arutyunyan <arut@nginx.com>
parents:
8595
diff
changeset
|
141 http3_hq (requires NGX_HTTP_V3_HQ macro) |
8016
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8005
diff
changeset
|
142 |
8712
651cc905b7c2
HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents:
8711
diff
changeset
|
143 In http, an additional variable is available: $http3. |
651cc905b7c2
HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents:
8711
diff
changeset
|
144 The value of $http3 is "h3" for HTTP/3 connections, |
651cc905b7c2
HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents:
8711
diff
changeset
|
145 "hq" for hq connections, or an empty string otherwise. |
651cc905b7c2
HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents:
8711
diff
changeset
|
146 |
651cc905b7c2
HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents:
8711
diff
changeset
|
147 In stream, an additional variable is available: $quic. |
7843 | 148 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
|
149 or an empty string otherwise. |
7843 | 150 |
151 Example configuration: | |
152 | |
153 http { | |
154 log_format quic '$remote_addr - $remote_user [$time_local] ' | |
155 '"$request" $status $body_bytes_sent ' | |
8718 | 156 '"$http_referer" "$http_user_agent" "$http3"'; |
7843 | 157 |
158 access_log logs/access.log quic; | |
159 | |
160 server { | |
161 # for better compatibility it's recommended | |
162 # to use the same port for quic and https | |
163 listen 8443 http3 reuseport; | |
164 listen 8443 ssl; | |
165 | |
166 ssl_certificate certs/example.com.crt; | |
167 ssl_certificate_key certs/example.com.key; | |
168 ssl_protocols TLSv1.3; | |
169 | |
170 location / { | |
171 # 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
|
172 add_header Alt-Svc 'h3=":8443"; ma=86400'; |
7843 | 173 } |
174 } | |
175 } | |
176 | |
177 4. Clients | |
178 | |
179 * Browsers | |
180 | |
8817
8f5d0ade0da7
README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8792
diff
changeset
|
181 Known to work: Firefox 90+ and Chrome 92+ (QUIC version 1) |
7843 | 182 |
183 Beware of strange issues: sometimes browser may decide to ignore QUIC | |
184 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
|
185 error.log to make sure the browser is using HTTP/3 and not TCP https. |
7843 | 186 |
187 * Console clients | |
188 | |
189 Known to work: ngtcp2, firefox's neqo and chromium's console clients: | |
190 | |
191 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html | |
192 | |
193 $ ./neqo-client https://127.0.0.1:8443/ | |
194 | |
8817
8f5d0ade0da7
README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8792
diff
changeset
|
195 $ chromium-build/out/my_build/quic_client http://example.com:8443 |
7843 | 196 |
197 | |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
198 In case everyhing is right, the access log should show something like: |
7843 | 199 |
200 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
|
201 "nghttp3/ngtcp2 client" "quic" |
7843 | 202 |
203 | |
204 5. Troubleshooting | |
205 | |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
206 Here are some tips that may help to identify problems: |
7843 | 207 |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
208 + Ensure nginx is built with proper SSL library that supports QUIC |
7843 | 209 |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
210 + 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
|
211 (`nginx -V` shows what it's using) |
7843 | 212 |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
213 + Ensure a client is actually sending requests over QUIC |
7843 | 214 (see "Clients" section about browsers and cache) |
215 | |
216 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
|
217 to ensure the server is configured properly before trying |
7872 | 218 with real browsers that may be very picky with certificates, |
7843 | 219 for example. |
220 | |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
221 + Build nginx with debug support [9] and check the debug log. |
7843 | 222 It should contain all details about connection and why it |
223 failed. All related messages contain "quic " prefix and can | |
224 be easily filtered out. | |
225 | |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
226 + 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
|
227 in src/event/quic/ngx_event_quic_connection.h: |
7843 | 228 |
229 #define NGX_QUIC_DEBUG_PACKETS | |
230 #define NGX_QUIC_DEBUG_FRAMES | |
8241
2dfc5ef29973
QUIC: introduced QUIC buffers.
Roman Arutyunyan <arut@nginx.com>
parents:
8160
diff
changeset
|
231 #define NGX_QUIC_DEBUG_ALLOC |
7843 | 232 #define NGX_QUIC_DEBUG_CRYPTO |
233 | |
7887
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
7879
diff
changeset
|
234 6. Contributing |
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
7879
diff
changeset
|
235 |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
236 Please refer to |
7887
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
7879
diff
changeset
|
237 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
|
238 |
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
7879
diff
changeset
|
239 7. Links |
7843 | 240 |
8488
8422570f6af4
README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8423
diff
changeset
|
241 [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
|
242 [2] https://datatracker.ietf.org/doc/html/rfc9114 |
8819
a7b789e2be27
README: updated link to nginx-devel mailman.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8818
diff
changeset
|
243 [3] https://mailman.nginx.org/mailman3/lists/nginx-devel.nginx.org/ |
7843 | 244 [4] https://boringssl.googlesource.com/boringssl/ |
8956
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
245 [5] https://www.libressl.org/ |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
246 [6] https://github.com/quictls/openssl |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
247 [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
|
248 [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
|
249 [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
|
250 [10] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf |