README: converted to passive voice, LibreSSL support.
This commit is contained in:
Sergey Kandaurov
parent
993631dea7
commit
628d0113ae
80
README
80
README
|
|
@ -23,16 +23,17 @@ Experimental QUIC support for nginx
|
|||
The code is currently at a beta level of quality, however
|
||||
there are several production deployments with it.
|
||||
|
||||
We are working on improving HTTP/3 support to integrate it into
|
||||
the main NGINX codebase. Thus, expect further updates of this code,
|
||||
including features, changes in behaviour, bug fixes, and refactoring.
|
||||
We'll be grateful for any feedback and code submissions.
|
||||
NGINX Development Team is working on improving HTTP/3 support to
|
||||
integrate it into the main NGINX codebase. Thus, expect further
|
||||
updates of this code, including features, changes in behaviour,
|
||||
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:
|
||||
|
||||
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
|
||||
it should be possible to upload and download big files without errors.
|
||||
|
|
@ -52,24 +53,40 @@ Experimental QUIC support for nginx
|
|||
|
||||
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
|
||||
$ cd nginx-quic
|
||||
|
||||
Use the following command to configure nginx with BoringSSL [4]
|
||||
|
||||
$ ./auto/configure --with-debug --with-http_v3_module \
|
||||
--with-cc-opt="-I../boringssl/include" \
|
||||
--with-ld-opt="-L../boringssl/build/ssl \
|
||||
-L../boringssl/build/crypto"
|
||||
$ 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 \
|
||||
--with-cc-opt="-I../quictls/build/include" \
|
||||
--with-ld-opt="-L../quictls/build/lib"
|
||||
|
||||
When configuring nginx, you can enable QUIC and HTTP/3 using the
|
||||
following new configuration options:
|
||||
Alternatively, nginx can be configured with a modern version
|
||||
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-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
|
||||
QUIC as client transport protocol instead of TCP or plain UDP.
|
||||
|
||||
Along with "http3" or "quic", you also have to specify "reuseport"
|
||||
option [6] to make it work properly with multiple workers.
|
||||
Along with "http3" or "quic", it's also possible to specify "reuseport"
|
||||
option [8] to make it work properly with multiple workers.
|
||||
|
||||
To enable address validation:
|
||||
|
||||
|
|
@ -110,8 +127,9 @@ Experimental QUIC support for nginx
|
|||
quic_host_key <filename>;
|
||||
|
||||
|
||||
By default, GSO Linux-specific optimization [8] is disabled.
|
||||
Enable if your network interface is configured to support GSO.
|
||||
By default, GSO Linux-specific optimization [10] is disabled.
|
||||
Enable it in case a corresponding network interface is configured to
|
||||
support GSO.
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
|
|
@ -177,7 +195,7 @@ Example configuration:
|
|||
$ 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 "-"
|
||||
"nghttp3/ngtcp2 client" "quic"
|
||||
|
|
@ -185,28 +203,28 @@ Example configuration:
|
|||
|
||||
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
|
||||
(`nginx -V` will show you what you are using)
|
||||
+ Ensure nginx is using the proper SSL library in runtime
|
||||
(`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)
|
||||
|
||||
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,
|
||||
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
|
||||
failed. All related messages contain "quic " prefix and can
|
||||
be easily filtered out.
|
||||
|
||||
+ If you want to investigate deeper, you may want to enable
|
||||
additional debugging in src/event/quic/ngx_event_quic_connection.h:
|
||||
+ For a deeper investigation, please enable additional debugging
|
||||
in src/event/quic/ngx_event_quic_connection.h:
|
||||
|
||||
#define NGX_QUIC_DEBUG_PACKETS
|
||||
#define NGX_QUIC_DEBUG_FRAMES
|
||||
|
|
@ -215,7 +233,7 @@ Example configuration:
|
|||
|
||||
6. Contributing
|
||||
|
||||
If you are willing to contribute, please refer to
|
||||
Please refer to
|
||||
http://nginx.org/en/docs/contributing_changes.html
|
||||
|
||||
7. Links
|
||||
|
|
@ -224,7 +242,9 @@ Example configuration:
|
|||
[2] https://datatracker.ietf.org/doc/html/rfc9114
|
||||
[3] https://mailman.nginx.org/mailman3/lists/nginx-devel.nginx.org/
|
||||
[4] https://boringssl.googlesource.com/boringssl/
|
||||
[5] https://github.com/quictls/openssl
|
||||
[6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen
|
||||
[7] https://nginx.org/en/docs/debugging_log.html
|
||||
[8] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf
|
||||
[5] https://www.libressl.org/
|
||||
[6] https://github.com/quictls/openssl
|
||||
[7] https://github.com/libressl-portable/portable/releases/tag/v3.6.0
|
||||
[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
|
||||
|
|
|
|||
Loading…
Reference in New Issue