Mercurial > hg > nginx

annotate README @ 9016:55b38514729b quic

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
QUIC: fixed insertion at the end of buffer. Previously, last buffer was tracked by keeping a pointer to the previous chain link "next" field. When the previous buffer was split and then removed, the pointer was no longer valid. Writing at this pointer resulted in broken data chains. Now last buffer is tracked by keeping a direct pointer to it.
author Roman Arutyunyan <arut@nginx.com>
date Thu, 17 Feb 2022 22:38:42 +0300
parents a7b789e2be27
children 0e74a77c2475
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
8982
8f5d0ade0da7 README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8966
diff changeset
37 We support IETF QUIC version 1. Internet drafts are no longer supported.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
38
8601
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8547
diff changeset
39 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
40 it should be possible to upload and download big files without errors.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
41
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
42 + The handshake completes successfully
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
43 + One endpoint can update keys and its peer responds correctly
8390
70dbd7d0e466 Fixed a typo.
Vladimir Homutov <vl@nginx.com>
parents: 8389
diff changeset
44 + 0-RTT data is being received and acted on
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
45 + 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
46 + A handshake that includes a Retry packet completes successfully
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
47 + Stream data is being exchanged and ACK'ed
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
48 + An H3 transaction succeeded
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
49 + One or both endpoints insert entries into dynamic table and
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
50 subsequently reference them from header blocks
8527
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8498
diff changeset
51 + Version Negotiation packet is sent to client with unknown version
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8498
diff changeset
52 + Lost packets are detected and retransmitted properly
8763
4117aa7fa38e QUIC: connection migration.
Vladimir Homutov <vl@nginx.com>
parents: 8747
diff changeset
53 + Clients may migrate to new address
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
54
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
55 2. Installing
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
56
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
57 You will need a BoringSSL [4] library that provides QUIC support
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
58
8373
796b5b6c43cd Mention quic branch in README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8372
diff changeset
59 $ hg clone -b quic https://hg.nginx.org/nginx-quic
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
60 $ cd nginx-quic
8966
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
61 $ ./auto/configure --with-debug --with-http_v3_module \
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
62 --with-cc-opt="-I../boringssl/include" \
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
63 --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
64 -L../boringssl/build/crypto"
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
65 $ make
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
66
8966
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
67 Alternatively, nginx can be configured with QuicTLS [9]
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
68
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../quictls/build/include" \
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
71 --with-ld-opt="-L../quictls/build/lib"
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
72
8487
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
73 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
74 following new configuration options:
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
75
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
76 --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
77 --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
78
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
79 3. Configuration
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
80
8922
be08b858086a HTTP/3: http3_hq directive and NGX_HTTP_V3_HQ macro.
Roman Arutyunyan <arut@nginx.com>
parents: 8840
diff changeset
81 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
82 HTTP/3 over QUIC on the specified port.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
83
8487
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
84 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
85 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
86
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 8449
diff changeset
87 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
88 option [6] to make it work properly with multiple workers.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
89
8402
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
90 To enable address validation:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
91
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
92 quic_retry on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
93
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
94 To enable 0-RTT:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
95
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
96 ssl_early_data on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
97
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
98 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
99
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
100 ssl_protocols TLSv1.3;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8396
diff changeset
101
8819
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
102 To enable GSO (Generic Segmentation Offloading):
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
103
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
104 quic_gso on;
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
105
8924
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
106 To limit maximum packet size:
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
107
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
108 quic_mtu <size>;
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
109
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
110 To set host key for various tokens:
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
111
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
112 quic_host_key <filename>;
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
113
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
114
8819
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8804
diff changeset
115 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
116 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
117
8498
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
118 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
119
8924
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
120 http3_stream_buffer_size
8498
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
121 http3_max_concurrent_pushes
8924
d6ef13c5fd8e QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents: 8923
diff changeset
122 http3_max_concurrent_streams
8498
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
123 http3_push
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8487
diff changeset
124 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
125 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
126
8923
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8922
diff changeset
127 In http, an additional variable is available: $http3.
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8922
diff changeset
128 The value of $http3 is "h3" for HTTP/3 connections,
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8922
diff changeset
129 "hq" for hq connections, or an empty string otherwise.
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8922
diff changeset
130
651cc905b7c2 HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents: 8922
diff changeset
131 In stream, an additional variable is available: $quic.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
132 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
133 or an empty string otherwise.
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
134
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
135 Example configuration:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
136
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
137 http {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
138 log_format quic '$remote_addr - $remote_user [$time_local] '
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
139 '"$request" $status $body_bytes_sent '
8929
44553428288d QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8924
diff changeset
140 '"$http_referer" "$http_user_agent" "$http3"';
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
141
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
142 access_log logs/access.log quic;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
143
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
144 server {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
145 # for better compatibility it's recommended
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
146 # to use the same port for quic and https
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
147 listen 8443 http3 reuseport;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
148 listen 8443 ssl;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
149
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
150 ssl_certificate certs/example.com.crt;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
151 ssl_certificate_key certs/example.com.key;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
152 ssl_protocols TLSv1.3;
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
153
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
154 location / {
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
155 # 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
156 add_header Alt-Svc 'h3=":8443"; ma=86400';
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 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
159 }
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
160
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
161 4. Clients
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
162
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
163 * Browsers
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
164
8982
8f5d0ade0da7 README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8966
diff changeset
165 Known to work: Firefox 90+ and Chrome 92+ (QUIC version 1)
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
166
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
167 Beware of strange issues: sometimes browser may decide to ignore QUIC
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
168 Cache clearing/restart might help. Always check access.log and
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
169 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
170
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
171 * Console clients
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
172
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
173 Known to work: ngtcp2, firefox's neqo and chromium's console clients:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
174
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
175 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
176
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
177 $ ./neqo-client https://127.0.0.1:8443/
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
178
8982
8f5d0ade0da7 README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8966
diff changeset
179 $ chromium-build/out/my_build/quic_client http://example.com:8443
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
180
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
181
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
182 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
183
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
184 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
185 "nghttp3/ngtcp2 client" "quic"
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
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
188 5. Troubleshooting
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
189
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
190 Here are some tips that may help you to identify problems:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
191
8601
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8547
diff changeset
192 + Ensure you are building with proper SSL library that supports QUIC
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
193
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
194 + Ensure you are using the proper SSL library in runtime
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
195 (`nginx -V` will show you what you are using)
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
196
8982
8f5d0ade0da7 README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8966
diff changeset
197 + Ensure your client is actually sending requests over QUIC
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
198 (see "Clients" section about browsers and cache)
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
199
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
200 We recommend to start with simple console client like ngtcp2
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
201 to ensure you've got server configured properly before trying
8395
578563babbd1 Fixed a typo.
Vladimir Homutov <vl@nginx.com>
parents: 8390
diff changeset
202 with real browsers that may be very picky with certificates,
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
203 for example.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
204
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
205 + Build nginx with debug support [7] and check your debug log.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
206 It should contain all details about connection and why it
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
207 failed. All related messages contain "quic " prefix and can
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
208 be easily filtered out.
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
209
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
210 + 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
211 additional debugging in src/event/quic/ngx_event_quic_connection.h:
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
212
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
213 #define NGX_QUIC_DEBUG_PACKETS
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
214 #define NGX_QUIC_DEBUG_FRAMES
8657
2dfc5ef29973 QUIC: introduced QUIC buffers.
Roman Arutyunyan <arut@nginx.com>
parents: 8601
diff changeset
215 #define NGX_QUIC_DEBUG_ALLOC
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
216 #define NGX_QUIC_DEBUG_CRYPTO
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
217
8410
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
218 6. Contributing
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
219
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
220 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
221 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
222
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 8402
diff changeset
223 7. Links
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
224
8787
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8763
diff changeset
225 [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
226 [2] https://datatracker.ietf.org/doc/html/draft-ietf-quic-http
8984
a7b789e2be27 README: updated link to nginx-devel mailman.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8983
diff changeset
227 [3] https://mailman.nginx.org/mailman3/lists/nginx-devel.nginx.org/
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
228 [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
229 [5] https://datatracker.ietf.org/doc/html/rfc9002
8366
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
230 [6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
231 [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
232 [8] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf
8966
6f8253673669 README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8929
diff changeset
233 [9] https://github.com/quictls/openssl