README: converted to passive voice, LibreSSL support.

This commit is contained in:
Sergey Kandaurov 2022-10-20 16:30:43 +04:00
parent 34500dcac3
commit 3cd06a3a9a

80
README
View File

@ -23,16 +23,17 @@ Experimental QUIC support for nginx
The code is currently at a beta level of quality, however The code is currently at a beta level of quality, however
there are several production deployments with it. there are several production deployments with it.
We are working on improving HTTP/3 support to integrate it into NGINX Development Team is working on improving HTTP/3 support to
the main NGINX codebase. Thus, expect further updates of this code, integrate it into the main NGINX codebase. Thus, expect further
including features, changes in behaviour, bug fixes, and refactoring. updates of this code, including features, changes in behaviour,
We'll be grateful for any feedback and code submissions. bug fixes, and refactoring. NGINX Development team will be
grateful for any feedback and code submissions.
You can always contact us via nginx-devel mailing list [3]. Please contact NGINX Development Team via nginx-devel mailing list [3].
What works now: What works now:
We support IETF QUIC version 1. Internet drafts are no longer supported. IETF QUIC version 1 is supported. Internet drafts are no longer supported.
nginx should be able to respond to HTTP/3 requests over QUIC and nginx should be able to respond to HTTP/3 requests over QUIC and
it should be possible to upload and download big files without errors. it should be possible to upload and download big files without errors.
@ -52,24 +53,40 @@ Experimental QUIC support for nginx
2. Installing 2. Installing
You will need a BoringSSL [4] library that provides QUIC support A library that provides QUIC support is required to build nginx, there
are several of those available on the market:
+ BoringSSL [4]
+ LibreSSL [5]
+ QuicTLS [6]
Clone the NGINX QUIC repository
$ hg clone -b quic https://hg.nginx.org/nginx-quic $ hg clone -b quic https://hg.nginx.org/nginx-quic
$ cd nginx-quic $ cd nginx-quic
Use the following command to configure nginx with BoringSSL [4]
$ ./auto/configure --with-debug --with-http_v3_module \ $ ./auto/configure --with-debug --with-http_v3_module \
--with-cc-opt="-I../boringssl/include" \ --with-cc-opt="-I../boringssl/include" \
--with-ld-opt="-L../boringssl/build/ssl \ --with-ld-opt="-L../boringssl/build/ssl \
-L../boringssl/build/crypto" -L../boringssl/build/crypto"
$ make $ make
Alternatively, nginx can be configured with QuicTLS [5] Alternatively, nginx can be configured with QuicTLS [6]
$ ./auto/configure --with-debug --with-http_v3_module \ $ ./auto/configure --with-debug --with-http_v3_module \
--with-cc-opt="-I../quictls/build/include" \ --with-cc-opt="-I../quictls/build/include" \
--with-ld-opt="-L../quictls/build/lib" --with-ld-opt="-L../quictls/build/lib"
When configuring nginx, you can enable QUIC and HTTP/3 using the Alternatively, nginx can be configured with a modern version
following new configuration options: of LibreSSL [7]
$ ./auto/configure --with-debug --with-http_v3_module \
--with-cc-opt="-I../libressl/build/include" \
--with-ld-opt="-L../libressl/build/lib"
When configuring nginx, it's possible to enable QUIC and HTTP/3
using the following new configuration options:
--with-http_v3_module - enable QUIC and HTTP/3 --with-http_v3_module - enable QUIC and HTTP/3
--with-stream_quic_module - enable QUIC in Stream --with-stream_quic_module - enable QUIC in Stream
@ -82,8 +99,8 @@ Experimental QUIC support for nginx
The Stream "listen" directive got a new option "quic" which enables The Stream "listen" directive got a new option "quic" which enables
QUIC as client transport protocol instead of TCP or plain UDP. QUIC as client transport protocol instead of TCP or plain UDP.
Along with "http3" or "quic", you also have to specify "reuseport" Along with "http3" or "quic", it's also possible to specify "reuseport"
option [6] to make it work properly with multiple workers. option [8] to make it work properly with multiple workers.
To enable address validation: To enable address validation:
@ -110,8 +127,9 @@ Experimental QUIC support for nginx
quic_host_key <filename>; quic_host_key <filename>;
By default, GSO Linux-specific optimization [8] is disabled. By default, GSO Linux-specific optimization [10] is disabled.
Enable if your network interface is configured to support GSO. Enable it in case a corresponding network interface is configured to
support GSO.
A number of directives were added that configure HTTP/3: A number of directives were added that configure HTTP/3:
@ -164,7 +182,7 @@ Example configuration:
Beware of strange issues: sometimes browser may decide to ignore QUIC Beware of strange issues: sometimes browser may decide to ignore QUIC
Cache clearing/restart might help. Always check access.log and Cache clearing/restart might help. Always check access.log and
error.log to make sure you are using HTTP/3 and not TCP https. error.log to make sure the browser is using HTTP/3 and not TCP https.
* Console clients * Console clients
@ -177,7 +195,7 @@ Example configuration:
$ chromium-build/out/my_build/quic_client http://example.com:8443 $ chromium-build/out/my_build/quic_client http://example.com:8443
If you've got it right, in the access log you should see something like: In case everyhing is right, the access log should show something like:
127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-" 127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-"
"nghttp3/ngtcp2 client" "quic" "nghttp3/ngtcp2 client" "quic"
@ -185,28 +203,28 @@ Example configuration:
5. Troubleshooting 5. Troubleshooting
Here are some tips that may help you to identify problems: Here are some tips that may help to identify problems:
+ Ensure you are building with proper SSL library that supports QUIC + Ensure nginx is built with proper SSL library that supports QUIC
+ Ensure you are using the proper SSL library in runtime + Ensure nginx is using the proper SSL library in runtime
(`nginx -V` will show you what you are using) (`nginx -V` shows what it's using)
+ Ensure your client is actually sending requests over QUIC + Ensure a client is actually sending requests over QUIC
(see "Clients" section about browsers and cache) (see "Clients" section about browsers and cache)
We recommend to start with simple console client like ngtcp2 We recommend to start with simple console client like ngtcp2
to ensure you've got server configured properly before trying to ensure the server is configured properly before trying
with real browsers that may be very picky with certificates, with real browsers that may be very picky with certificates,
for example. for example.
+ Build nginx with debug support [7] and check your debug log. + Build nginx with debug support [9] and check the debug log.
It should contain all details about connection and why it It should contain all details about connection and why it
failed. All related messages contain "quic " prefix and can failed. All related messages contain "quic " prefix and can
be easily filtered out. be easily filtered out.
+ If you want to investigate deeper, you may want to enable + For a deeper investigation, please enable additional debugging
additional debugging in src/event/quic/ngx_event_quic_connection.h: in src/event/quic/ngx_event_quic_connection.h:
#define NGX_QUIC_DEBUG_PACKETS #define NGX_QUIC_DEBUG_PACKETS
#define NGX_QUIC_DEBUG_FRAMES #define NGX_QUIC_DEBUG_FRAMES
@ -215,7 +233,7 @@ Example configuration:
6. Contributing 6. Contributing
If you are willing to contribute, please refer to Please refer to
http://nginx.org/en/docs/contributing_changes.html http://nginx.org/en/docs/contributing_changes.html
7. Links 7. Links
@ -224,7 +242,9 @@ Example configuration:
[2] https://datatracker.ietf.org/doc/html/rfc9114 [2] https://datatracker.ietf.org/doc/html/rfc9114
[3] https://mailman.nginx.org/mailman3/lists/nginx-devel.nginx.org/ [3] https://mailman.nginx.org/mailman3/lists/nginx-devel.nginx.org/
[4] https://boringssl.googlesource.com/boringssl/ [4] https://boringssl.googlesource.com/boringssl/
[5] https://github.com/quictls/openssl [5] https://www.libressl.org/
[6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen [6] https://github.com/quictls/openssl
[7] https://nginx.org/en/docs/debugging_log.html [7] https://github.com/libressl-portable/portable/releases/tag/v3.6.0
[8] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf [8] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen
[9] https://nginx.org/en/docs/debugging_log.html
[10] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf