annotate README @ 8922:be08b858086a quic

HTTP/3: http3_hq directive and NGX_HTTP_V3_HQ macro. Listen quic parameter is no longer supported.
author Roman Arutyunyan <arut@nginx.com>
date Sat, 04 Dec 2021 10:52:55 +0300
parents 4d871baeacd2
children 651cc905b7c2
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
8787
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8763
diff changeset
18 on nginx mainline 1.21.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
8601
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8547
diff changeset
23 The code is currently at a beta level of quality and should not
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
24 be used in production.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
25
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
26 We are working on improving HTTP/3 support with the goal of
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
27 integrating it to the main NGINX codebase. Expect frequent
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
28 updates of this code and don't rely on it for whatever purpose.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
29
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
30 We'll be grateful for any feedback and code submissions however
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
31 we don't bear any responsibilities for any issues with this code.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
32
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
33 You can always contact us via nginx-devel mailing list [3].
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
8787
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8763
diff changeset
37 Currently we support IETF-QUIC draft-29 through final RFC documents.
8449
3c32717d7bb2 README: documented draft-28, draft-29 support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8412
diff changeset
38 Earlier drafts are NOT supported as they have incompatible wire format.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
39
8601
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8547
diff changeset
40 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
41 it should be possible to upload and download big files without errors.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
42
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
43 + The handshake completes successfully
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
44 + One endpoint can update keys and its peer responds correctly
8390
70dbd7d0e466 Fixed a typo.
Vladimir Homutov <vl@nginx.com>
parents: 8389
diff changeset
45 + 0-RTT data is being received and acted on
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
46 + 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
47 + A handshake that includes a Retry packet completes successfully
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
48 + Stream data is being exchanged and ACK'ed
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
49 + An H3 transaction succeeded
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
50 + One or both endpoints insert entries into dynamic table and
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
51 subsequently reference them from header blocks
8527
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8498
diff changeset
52 + Version Negotiation packet is sent to client with unknown version
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8498
diff changeset
53 + Lost packets are detected and retransmitted properly
8763
4117aa7fa38e QUIC: connection migration.
Vladimir Homutov <vl@nginx.com>
parents: 8747
diff changeset
54 + Clients may migrate to new address
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
55
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
56 Not (yet) supported features:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
57
8527
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8498
diff changeset
58 - Explicit Congestion Notification (ECN) as specified in quic-recovery [5]
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
59 - A connection with the spin bit succeeds and the bit is spinning
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
60 - Structured Logging
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
61
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
62 Since the code is experimental and still under development,
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
63 a lot of things may not work as expected, for example:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
64
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
65 - Flow control mechanism is basic and intended to avoid CPU hog and make
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
66 simple interactions possible
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
67
8787
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8763
diff changeset
68 - Not all protocol requirements are strictly followed; some of checks are
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
69 omitted for the sake of simplicity of initial implementation
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
70
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
71 2. Installing
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
72
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
73 You will need a BoringSSL [4] library that provides QUIC support
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
74
8373
796b5b6c43cd Mention quic branch in README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8372
diff changeset
75 $ hg clone -b quic https://hg.nginx.org/nginx-quic
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
76 $ cd nginx-quic
8372
0e6528551f26 Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8366
diff changeset
77 $ ./auto/configure --with-debug --with-http_v3_module \
0e6528551f26 Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8366
diff changeset
78 --with-cc-opt="-I../boringssl/include" \
0e6528551f26 Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8366
diff changeset
79 --with-ld-opt="-L../boringssl/build/ssl \
0e6528551f26 Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8366
diff changeset
80 -L../boringssl/build/crypto"
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
81 $ make
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
82
8487
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
83 When configuring nginx, you can enable QUIC and HTTP/3 using the
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
84 following new configuration options:
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
85
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
86 --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
87 --with-http_quic_module - enable QUIC for older HTTP versions
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
88 --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
89
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
90 3. Configuration
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
91
8922
be08b858086a HTTP/3: http3_hq directive and NGX_HTTP_V3_HQ macro.
Roman Arutyunyan <arut@nginx.com>
parents: 8840
diff changeset
92 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
93 HTTP/3 over QUIC on the specified port.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
94
8487
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
95 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
96 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
97
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
98 Along with "http3" or "quic", you also have to specify "reuseport"
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
99 option [6] to make it work properly with multiple workers.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
100
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
101 A number of directives were added that specify transport parameter values:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
102
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
103 quic_max_idle_timeout
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
104 quic_max_ack_delay
8684
27bd6dc24426 README: reflect renaming of several transport parameter directives.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8657
diff changeset
105 quic_max_udp_payload_size
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
106 quic_initial_max_data
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
107 quic_initial_max_stream_data_bidi_local
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
108 quic_initial_max_stream_data_bidi_remote
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
109 quic_initial_max_stream_data_uni
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
110 quic_initial_max_streams_bidi
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
111 quic_initial_max_streams_uni
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
112 quic_ack_delay_exponent
8684
27bd6dc24426 README: reflect renaming of several transport parameter directives.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8657
diff changeset
113 quic_disable_active_migration
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
114 quic_active_connection_id_limit
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
115
8402
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
116 To enable address validation:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
117
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
118 quic_retry on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
119
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
120 To enable 0-RTT:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
121
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
122 ssl_early_data on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
123
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
124 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
125
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
126 ssl_protocols TLSv1.3;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
127
8819
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
128 To enable GSO (Generic Segmentation Offloading):
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
129
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
130 quic_gso on;
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
131
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
132 By default this Linux-specific optimization [8] is disabled.
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
133 Enable if your network interface is configured to support GSO.
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
134
8498
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
135 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
136
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
137 http3_max_table_capacity
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
138 http3_max_blocked_streams
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
139 http3_max_concurrent_pushes
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
140 http3_push
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
141 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
142 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
143
8788
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8787
diff changeset
144 An additional variable is available: $quic.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
145 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
146 or an empty string otherwise.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
147
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
148 Example configuration:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
149
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
150 http {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
151 log_format quic '$remote_addr - $remote_user [$time_local] '
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
152 '"$request" $status $body_bytes_sent '
8788
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8787
diff changeset
153 '"$http_referer" "$http_user_agent" "$quic"';
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
154
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
155 access_log logs/access.log quic;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
156
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
157 server {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
158 # for better compatibility it's recommended
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
159 # to use the same port for quic and https
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
160 listen 8443 http3 reuseport;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
161 listen 8443 ssl;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
162
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
163 ssl_certificate certs/example.com.crt;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
164 ssl_certificate_key certs/example.com.key;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
165 ssl_protocols TLSv1.3;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
166
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
167 location / {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
168 # 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
169 add_header Alt-Svc 'h3=":8443"; ma=86400';
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
170 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
171 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
172 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
173
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
174 4. Clients
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
175
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
176 * Browsers
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
177
8712
6da4b045ec34 README: bump browsers' version after 81bb3a690c10 (old drafts rip).
Sergey Kandaurov <pluknet@nginx.com>
parents: 8711
diff changeset
178 Known to work: Firefox 80+ and Chrome 85+ (QUIC draft 29+)
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
179
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
180 Beware of strange issues: sometimes browser may decide to ignore QUIC
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
181 Cache clearing/restart might help. Always check access.log and
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
182 error.log to make sure you are using HTTP/3 and not TCP https.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
183
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
184 + to enable QUIC in Firefox, set the following in 'about:config':
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
185 network.http.http3.enabled = true
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
186
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
187 + to enable QUIC in Chrome, enable it on command line and force it
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
188 on your site:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
189
8547
57e5393e5d40 QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents: 8527
diff changeset
190 $ ./chrome --enable-quic --quic-version=h3-29 \
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
191 --origin-to-force-quic-on=example.com:8443
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
192
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
193 * Console clients
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
194
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
195 Known to work: ngtcp2, firefox's neqo and chromium's console clients:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
196
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
197 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
198
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
199 $ ./neqo-client https://127.0.0.1:8443/
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
200
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
201 $ chromium-build/out/my_build/quic_client http://example.com:8443 \
8547
57e5393e5d40 QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents: 8527
diff changeset
202 --quic_version=h3-29 \
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
203 --allow_unknown_root_cert \
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
204 --disable_certificate_verification
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
205
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
206
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
207 If you've got it right, in the access log you should see something like:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
208
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
209 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
210 "nghttp3/ngtcp2 client" "quic"
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
211
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
212
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
213 5. Troubleshooting
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
214
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
215 Here are some tips that may help you to identify problems:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
216
8601
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8547
diff changeset
217 + Ensure you are building with proper SSL library that supports QUIC
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
218
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
219 + Ensure you are using the proper SSL library in runtime
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
220 (`nginx -V` will show you what you are using)
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
221
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
222 + Ensure your client is actually sending QUIC requests
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
223 (see "Clients" section about browsers and cache)
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
224
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
225 We recommend to start with simple console client like ngtcp2
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
226 to ensure you've got server configured properly before trying
8395
578563babbd1 Fixed a typo.
Vladimir Homutov <vl@nginx.com>
parents: 8390
diff changeset
227 with real browsers that may be very picky with certificates,
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
228 for example.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
229
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
230 + Build nginx with debug support [7] and check your debug log.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
231 It should contain all details about connection and why it
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
232 failed. All related messages contain "quic " prefix and can
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
233 be easily filtered out.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
234
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
235 + If you want to investigate deeper, you may want to enable
8804
d56c7c4b66fd README: updated path after moving QUIC sources.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8788
diff changeset
236 additional debugging in src/event/quic/ngx_event_quic_connection.h:
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
237
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
238 #define NGX_QUIC_DEBUG_PACKETS
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
239 #define NGX_QUIC_DEBUG_FRAMES
8657
2dfc5ef29973 QUIC: introduced QUIC buffers.
Roman Arutyunyan <arut@nginx.com>
parents: 8601
diff changeset
240 #define NGX_QUIC_DEBUG_ALLOC
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
241 #define NGX_QUIC_DEBUG_CRYPTO
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
242
8410
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
243 6. Contributing
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
244
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
245 If you are willing to contribute, please refer to
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
246 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
247
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
248 7. Links
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
249
8787
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8763
diff changeset
250 [1] https://datatracker.ietf.org/doc/html/rfc9000
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8763
diff changeset
251 [2] https://datatracker.ietf.org/doc/html/draft-ietf-quic-http
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
252 [3] https://mailman.nginx.org/mailman/listinfo/nginx-devel
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
253 [4] https://boringssl.googlesource.com/boringssl/
8787
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8763
diff changeset
254 [5] https://datatracker.ietf.org/doc/html/rfc9002
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
255 [6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
256 [7] https://nginx.org/en/docs/debugging_log.html
8819
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
257 [8] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf