annotate README @ 8702:40445fc7c403 quic

QUIC: fixed migration during NAT rebinding. The RFC 9000 allows a packet from known CID arrive from unknown path: These requirements regarding connection ID reuse apply only to the sending of packets, as unintentional changes in path without a change in connection ID are possible. For example, after a period of network inactivity, NAT rebinding might cause packets to be sent on a new path when the client resumes sending. Before the patch, such packets were rejected with an error in the ngx_quic_check_migration() function. Removing the check makes the separate function excessive - remaining checks are early migration check and "disable_active_migration" check. The latter is a transport parameter sent to client and it should not be used by server. The server should send "disable_active_migration" "if the endpoint does not support active connection migration" (18.2). The support status depends on nginx configuration: to have migration working with multiple workers, you need bpf helper, available on recent Linux systems. The patch does not set "disable_active_migration" automatically and leaves it for the administrator. By default, active migration is enabled. RFC 900 says that it is ok to migrate if the peer violates "disable_active_migration" flag requirements: If the peer violates this requirement, the endpoint MUST either drop the incoming packets on that path without generating a Stateless Reset OR proceed with path validation and allow the peer to migrate. Generating a Stateless Reset or closing the connection would allow third parties in the network to cause connections to close by spoofing or otherwise manipulating observed traffic. So, nginx adheres to the second option and proceeds to path validation. Note: The ngtcp2 may be used for testing both active migration and NAT rebinding: ngtcp2/client --change-local-addr=200ms --delay-stream=500ms <ip> <port> <url> ngtcp2/client --change-local-addr=200ms --delay-stream=500ms --nat-rebinding \ <ip> <port> <url>
author Vladimir Homutov <vl@nginx.com>
date Mon, 29 Nov 2021 11:51:14 +0300
parents 4d871baeacd2
children be08b858086a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
1 Experimental QUIC support for nginx
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
2 -----------------------------------
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
3
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
4 1. Introduction
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
7887
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 7879
diff changeset
9 6. Contributing
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 7879
diff changeset
10 7. Links
7843
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
8488
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8423
diff changeset
18 on nginx mainline 1.21.x. We merge new nginx releases into
8160
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8085
diff changeset
19 this branch regularly.
7843
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
8160
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8085
diff changeset
23 The code is currently at a beta level of quality and should not
7843
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
8488
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8423
diff changeset
37 Currently we support IETF-QUIC draft-29 through final RFC documents.
7944
3c32717d7bb2 README: documented draft-28, draft-29 support.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7907
diff changeset
38 Earlier drafts are NOT supported as they have incompatible wire format.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
39
8160
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8085
diff changeset
40 nginx should be able to respond to HTTP/3 requests over QUIC and
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
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
7867
70dbd7d0e466 Fixed a typo.
Vladimir Homutov <vl@nginx.com>
parents: 7866
diff changeset
45 + 0-RTT data is being received and acted on
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
46 + Connection is established using TLS Resume Ticket
7866
2b580ac17a47 README: Retry support, protocol error messages implemented.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7850
diff changeset
47 + A handshake that includes a Retry packet completes successfully
7843
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
8065
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8016
diff changeset
52 + Version Negotiation packet is sent to client with unknown version
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8016
diff changeset
53 + Lost packets are detected and retransmitted properly
8423
4117aa7fa38e QUIC: connection migration.
Vladimir Homutov <vl@nginx.com>
parents: 8407
diff changeset
54 + Clients may migrate to new address
7843
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
8065
cec7f207a4bf QUIC: updated README.
Vladimir Homutov <vl@nginx.com>
parents: 8016
diff changeset
58 - Explicit Congestion Notification (ECN) as specified in quic-recovery [5]
7843
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
8488
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8423
diff changeset
68 - Not all protocol requirements are strictly followed; some of checks are
7843
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
7850
796b5b6c43cd Mention quic branch in README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7849
diff changeset
75 $ hg clone -b quic https://hg.nginx.org/nginx-quic
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
76 $ cd nginx-quic
7849
0e6528551f26 Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7843
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: 7843
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: 7843
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: 7843
diff changeset
80 -L../boringssl/build/crypto"
7843
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
8005
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
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: 7944
diff changeset
84 following new configuration options:
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
diff changeset
85
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
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: 7944
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: 7944
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: 7944
diff changeset
89
7843
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
8005
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
diff changeset
92 The HTTP "listen" directive got two new options: "http3" and "quic".
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
diff changeset
93 The "http3" option enables HTTP/3 over QUIC on the specified port.
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
diff changeset
94 The "quic" option enables QUIC for older HTTP versions on this port.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
95
8005
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
diff changeset
96 The Stream "listen" directive got a new option "quic" which enables
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
diff changeset
97 QUIC as client transport protocol instead of TCP or plain UDP.
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
diff changeset
98
6e84524886d4 QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents: 7944
diff changeset
99 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: 7944
diff changeset
100 option [6] to make it work properly with multiple workers.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
101
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
102 A number of directives were added that specify transport parameter values:
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
103
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
104 quic_max_idle_timeout
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
105 quic_max_ack_delay
8277
27bd6dc24426 README: reflect renaming of several transport parameter directives.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8241
diff changeset
106 quic_max_udp_payload_size
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
107 quic_initial_max_data
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
108 quic_initial_max_stream_data_bidi_local
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
109 quic_initial_max_stream_data_bidi_remote
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
110 quic_initial_max_stream_data_uni
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
111 quic_initial_max_streams_bidi
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
112 quic_initial_max_streams_uni
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
113 quic_ack_delay_exponent
8277
27bd6dc24426 README: reflect renaming of several transport parameter directives.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8241
diff changeset
114 quic_disable_active_migration
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
115 quic_active_connection_id_limit
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
116
7879
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
117 To enable address validation:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
118
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
119 quic_retry on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
120
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
121 To enable 0-RTT:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
122
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
123 ssl_early_data on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
124
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
125 Make sure that TLS 1.3 is configured which is required for QUIC:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
126
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
127 ssl_protocols TLSv1.3;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents: 7873
diff changeset
128
8544
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
129 To enable GSO (Generic Segmentation Offloading):
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
130
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
131 quic_gso on;
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
132
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
133 By default this Linux-specific optimization [8] is disabled.
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
134 Enable if your network interface is configured to support GSO.
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
135
8016
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
136 A number of directives were added that configure HTTP/3:
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
137
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
138 http3_max_table_capacity
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
139 http3_max_blocked_streams
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
140 http3_max_concurrent_pushes
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
141 http3_push
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
142 http3_push_preload
affb0245e291 QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents: 8005
diff changeset
143
8489
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8488
diff changeset
144 An additional variable is available: $quic.
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
145 The value of $quic is "quic" if QUIC connection is used,
8489
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8488
diff changeset
146 or an empty string otherwise.
7843
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 '
8489
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8488
diff changeset
153 '"$http_referer" "$http_user_agent" "$quic"';
7843
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
8489
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8488
diff changeset
169 add_header Alt-Svc 'h3=":8443"; ma=86400';
7843
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
8324
6da4b045ec34 README: bump browsers' version after 81bb3a690c10 (old drafts rip).
Sergey Kandaurov <pluknet@nginx.com>
parents: 8323
diff changeset
178 Known to work: Firefox 80+ and Chrome 85+ (QUIC draft 29+)
7843
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
8085
57e5393e5d40 QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents: 8065
diff changeset
190 $ ./chrome --enable-quic --quic-version=h3-29 \
7843
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 \
8085
57e5393e5d40 QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents: 8065
diff changeset
202 --quic_version=h3-29 \
7843
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 "-"
8489
f0882db8c8d4 HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8488
diff changeset
210 "nghttp3/ngtcp2 client" "quic"
7843
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
8160
dd8e50e11bfc QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8085
diff changeset
217 + Ensure you are building with proper SSL library that supports QUIC
7843
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
7872
578563babbd1 Fixed a typo.
Vladimir Homutov <vl@nginx.com>
parents: 7867
diff changeset
227 with real browsers that may be very picky with certificates,
7843
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
8505
d56c7c4b66fd README: updated path after moving QUIC sources.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8489
diff changeset
236 additional debugging in src/event/quic/ngx_event_quic_connection.h:
7843
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
8241
2dfc5ef29973 QUIC: introduced QUIC buffers.
Roman Arutyunyan <arut@nginx.com>
parents: 8160
diff changeset
240 #define NGX_QUIC_DEBUG_ALLOC
7843
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
7887
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 7879
diff changeset
243 6. Contributing
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 7879
diff changeset
244
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 7879
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: 7879
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: 7879
diff changeset
247
c7d1b500bd0a Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents: 7879
diff changeset
248 7. Links
7843
3e894ace66ee Added README.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
249
8488
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8423
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: 8423
diff changeset
251 [2] https://datatracker.ietf.org/doc/html/draft-ietf-quic-http
7843
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/
8488
8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents: 8423
diff changeset
254 [5] https://datatracker.ietf.org/doc/html/rfc9002
7843
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
8544
d0ef43a53a51 QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents: 8505
diff changeset
257 [8] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf