diff options
| -rw-r--r-- | README | 80 |
1 files changed, 50 insertions, 30 deletions
@@ -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 |