Mercurial > hg > nginx

annotate README @ 9034:79cd6993a3e3 quic

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
README: converted to passive voice, LibreSSL support.
author Sergey Kandaurov <pluknet@nginx.com>
date Thu, 20 Oct 2022 16:30:43 +0400
parents 98e94553ae51
children 3c33d39a51d3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8366
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
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
5 2. Installing
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
6 3. Configuration
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
7 4. Clients
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
8 5. Troubleshooting
8410
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
9 6. Contributing
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
10 7. Links
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
11
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
12 1. Introduction
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
13
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
14 This is an experimental QUIC [1] / HTTP/3 [2] support for nginx.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
15
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
16 The code is developed in a separate "quic" branch available
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
17 at https://hg.nginx.org/nginx-quic. Currently it is based
9021
8d0753760546 Merged with the default branch.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9019
diff changeset
18 on nginx mainline 1.23.x. We merge new nginx releases into
8601
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8547
diff changeset
19 this branch regularly.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
20
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
21 The project code base is under the same BSD license as nginx.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
22
9028
98e94553ae51 README: updated the current status.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9021
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: 9021
diff changeset
24 there are several production deployments with it.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
25
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
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: 9028
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: 9028
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: 9028
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: 9028
diff changeset
30 grateful for any feedback and code submissions.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
31
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
32 Please contact NGINX Development Team via nginx-devel mailing list [3].
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
33
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
34 What works now:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
35
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
36 IETF QUIC version 1 is supported. Internet drafts are no longer supported.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
37
8601
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8547
diff changeset
38 nginx should be able to respond to HTTP/3 requests over QUIC and
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
39 it should be possible to upload and download big files without errors.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
40
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
41 + The handshake completes successfully
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
42 + One endpoint can update keys and its peer responds correctly
8390
70dbd7d0e466 Fixed a typo.
Vladimir Homutov <vl@nginx.com>
parents: 8389
diff changeset
43 + 0-RTT data is being received and acted on
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
44 + Connection is established using TLS Resume Ticket
8389
2b580ac17a47 README: Retry support, protocol error messages implemented.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8373
diff changeset
45 + A handshake that includes a Retry packet completes successfully
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
46 + Stream data is being exchanged and ACK'ed
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
47 + An H3 transaction succeeded
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
48 + One or both endpoints insert entries into dynamic table and
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
49 subsequently reference them from header blocks
8527
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8498
diff changeset
50 + Version Negotiation packet is sent to client with unknown version
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8498
diff changeset
51 + Lost packets are detected and retransmitted properly
8763
4117aa7fa38e QUIC: connection migration.
Vladimir Homutov <vl@nginx.com>
parents: 8747
diff changeset
52 + Clients may migrate to new address
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
53
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
54 2. Installing
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
55
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
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: 9028
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: 9028
diff changeset
58 + BoringSSL [4]
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
59 + LibreSSL [5]
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
60 + QuicTLS [6]
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
61
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
62 Clone the NGINX QUIC repository
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
63
8373
796b5b6c43cd Mention quic branch in README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8372
diff changeset
64 $ hg clone -b quic https://hg.nginx.org/nginx-quic
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
65 $ cd nginx-quic
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
66
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
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: 9028
diff changeset
68
8966
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
69 $ ./auto/configure --with-debug --with-http_v3_module \
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
70 --with-cc-opt="-I../boringssl/include" \
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
71 --with-ld-opt="-L../boringssl/build/ssl \
8372
0e6528551f26 Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8366
diff changeset
72 -L../boringssl/build/crypto"
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
73 $ make
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
74
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
75 Alternatively, nginx can be configured with QuicTLS [6]
8966
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
76
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
77 $ ./auto/configure --with-debug --with-http_v3_module \
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
78 --with-cc-opt="-I../quictls/build/include" \
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
79 --with-ld-opt="-L../quictls/build/lib"
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
80
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
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: 9028
diff changeset
82 of LibreSSL [7]
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
83
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
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: 9028
diff changeset
85 --with-cc-opt="-I../libressl/build/include" \
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
86 --with-ld-opt="-L../libressl/build/lib"
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
87
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
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: 9028
diff changeset
89 using the following new configuration options:
8487
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
90
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
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: 8449
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: 8449
diff changeset
93
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
94 3. Configuration
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
95
8922
be08b858086a HTTP/3: http3_hq directive and NGX_HTTP_V3_HQ macro.
Roman Arutyunyan <arut@nginx.com>
parents: 8840
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: 8840
diff changeset
97 HTTP/3 over QUIC on the specified port.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
98
8487
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
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: 8449
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: 8449
diff changeset
101
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
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: 9028
diff changeset
103 option [8] to make it work properly with multiple workers.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
104
8402
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
105 To enable address validation:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
106
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
107 quic_retry on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
108
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
109 To enable 0-RTT:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
110
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
111 ssl_early_data on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
112
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
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: 8396
diff changeset
114
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
115 ssl_protocols TLSv1.3;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
116
8819
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
117 To enable GSO (Generic Segmentation Offloading):
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
118
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
119 quic_gso on;
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
120
9019
0e74a77c2475 README: updated after HTTP/3 RFC publication, minor refinements.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8984
diff changeset
121 To limit maximum UDP payload size on receive path:
8924
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
122
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
123 quic_mtu <size>;
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
124
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
125 To set host key for various tokens:
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
126
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
127 quic_host_key <filename>;
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
128
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
129
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
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: 9028
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: 9028
diff changeset
132 support GSO.
8819
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
133
8498
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
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: 8487
diff changeset
135
8924
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
136 http3_stream_buffer_size
8498
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
137 http3_max_concurrent_pushes
8924
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
138 http3_max_concurrent_streams
8498
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
139 http3_push
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
140 http3_push_preload
8922
be08b858086a HTTP/3: http3_hq directive and NGX_HTTP_V3_HQ macro.
Roman Arutyunyan <arut@nginx.com>
parents: 8840
diff changeset
141 http3_hq (requires NGX_HTTP_V3_HQ macro)
8498
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
142
8923
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8922
diff changeset
143 In http, an additional variable is available: $http3.
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8922
diff changeset
144 The value of $http3 is "h3" for HTTP/3 connections,
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8922
diff changeset
145 "hq" for hq connections, or an empty string otherwise.
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8922
diff changeset
146
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8922
diff changeset
147 In stream, an additional variable is available: $quic.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
148 The value of $quic is "quic" if QUIC connection is used,
8788
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8787
diff changeset
149 or an empty string otherwise.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
150
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
151 Example configuration:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
152
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
153 http {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
154 log_format quic '$remote_addr - $remote_user [$time_local] '
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
155 '"$request" $status $body_bytes_sent '
8929
44553428288d QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8924
diff changeset
156 '"$http_referer" "$http_user_agent" "$http3"';
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
157
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
158 access_log logs/access.log quic;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
159
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
160 server {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
161 # for better compatibility it's recommended
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
162 # to use the same port for quic and https
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
163 listen 8443 http3 reuseport;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
164 listen 8443 ssl;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
165
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
166 ssl_certificate certs/example.com.crt;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
167 ssl_certificate_key certs/example.com.key;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
168 ssl_protocols TLSv1.3;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
169
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
170 location / {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
171 # required for browsers to direct them into quic port
8788
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8787
diff changeset
172 add_header Alt-Svc 'h3=":8443"; ma=86400';
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
173 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
174 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
175 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
176
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
177 4. Clients
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
178
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
179 * Browsers
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
180
8982
8f5d0ade0da7 README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8966
diff changeset
181 Known to work: Firefox 90+ and Chrome 92+ (QUIC version 1)
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
182
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
183 Beware of strange issues: sometimes browser may decide to ignore QUIC
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
184 Cache clearing/restart might help. Always check access.log and
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
185 error.log to make sure the browser is using HTTP/3 and not TCP https.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
186
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
187 * Console clients
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
188
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
189 Known to work: ngtcp2, firefox's neqo and chromium's console clients:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
190
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
191 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
192
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
193 $ ./neqo-client https://127.0.0.1:8443/
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
194
8982
8f5d0ade0da7 README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8966
diff changeset
195 $ chromium-build/out/my_build/quic_client http://example.com:8443
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
196
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
197
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
198 In case everyhing is right, the access log should show something like:
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
199
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
200 127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-"
8788
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8787
diff changeset
201 "nghttp3/ngtcp2 client" "quic"
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
202
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
203
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
204 5. Troubleshooting
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
205
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
206 Here are some tips that may help to identify problems:
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
207
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
208 + Ensure nginx is built with proper SSL library that supports QUIC
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
209
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
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: 9028
diff changeset
211 (`nginx -V` shows what it's using)
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
212
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
213 + Ensure a client is actually sending requests over QUIC
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
214 (see "Clients" section about browsers and cache)
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
215
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
216 We recommend to start with simple console client like ngtcp2
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
217 to ensure the server is configured properly before trying
8395
578563babbd1 Fixed a typo.
Vladimir Homutov <vl@nginx.com>
parents: 8390
diff changeset
218 with real browsers that may be very picky with certificates,
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
219 for example.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
220
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
221 + Build nginx with debug support [9] and check the debug log.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
222 It should contain all details about connection and why it
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
223 failed. All related messages contain "quic " prefix and can
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
224 be easily filtered out.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
225
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
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: 9028
diff changeset
227 in src/event/quic/ngx_event_quic_connection.h:
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
228
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
229 #define NGX_QUIC_DEBUG_PACKETS
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
230 #define NGX_QUIC_DEBUG_FRAMES
8657
2dfc5ef29973 QUIC: introduced QUIC buffers.
Roman Arutyunyan <arut@nginx.com>
parents: 8601
diff changeset
231 #define NGX_QUIC_DEBUG_ALLOC
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
232 #define NGX_QUIC_DEBUG_CRYPTO
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
233
8410
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
234 6. Contributing
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
235
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
236 Please refer to
8410
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
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: 8402
diff changeset
238
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
239 7. Links
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
240
8787
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8763
diff changeset
241 [1] https://datatracker.ietf.org/doc/html/rfc9000
9019
0e74a77c2475 README: updated after HTTP/3 RFC publication, minor refinements.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8984
diff changeset
242 [2] https://datatracker.ietf.org/doc/html/rfc9114
8984
a7b789e2be27 README: updated link to nginx-devel mailman.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8983
diff changeset
243 [3] https://mailman.nginx.org/mailman3/lists/nginx-devel.nginx.org/
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
244 [4] https://boringssl.googlesource.com/boringssl/
9034
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
245 [5] https://www.libressl.org/
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
diff changeset
246 [6] https://github.com/quictls/openssl
79cd6993a3e3 README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 9028
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: 9028
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: 9028
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: 9028
diff changeset
250 [10] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf