+ rev="21">

@@ -238,7 +238,7 @@ enables building a module that provides This module is not built by default. - + --with-http_v3_module

diff --git a/xml/en/docs/http/ngx_http_core_module.xml b/xml/en/docs/http/ngx_http_core_module.xml --- a/xml/en/docs/http/ngx_http_core_module.xml +++ b/xml/en/docs/http/ngx_http_core_module.xml @@ -10,7 +10,7 @@ + rev="104">

@@ -1390,7 +1390,7 @@ connections without SSL. -The quic parameter (1.23.4) configures the port to accept +The quic parameter (1.25.0) configures the port to accept QUIC connections. diff --git a/xml/en/docs/http/ngx_http_v3_module.xml b/xml/en/docs/http/ngx_http_v3_module.xml --- a/xml/en/docs/http/ngx_http_v3_module.xml +++ b/xml/en/docs/http/ngx_http_v3_module.xml @@ -9,19 +9,19 @@ + rev="2">

-The ngx_http_v3_module module (1.23.4) provides +The ngx_http_v3_module module (1.25.0) provides experimental support for HTTP/3. This module is not built by default, it should be enabled with the ---with-http_v3_module +--with-http_v3_module configuration parameter. An SSL library that provides QUIC support @@ -37,18 +37,6 @@ OpenSSL compatibility layer will be used - - - -The module is available as -nginx-quic in -prebult Linux packages. -The module is also available as part of our -commercial subscription -in a separate nginx-plus-quic package. - - -

@@ -129,20 +117,6 @@ interoperability tests. - -number -10 -http -server - - -Limits the maximum number of concurrent -push requests in a connection. - - - - - number 128 @@ -157,56 +131,6 @@ in a connection. - -uri | off -off -http -server -location - - -Pre-emptively sends -(pushes) -a request to the specified uri -along with the response to the original request. -Only relative URIs with absolute path will be processed, -for example: - -http3_push /static/css/main.css; - -The uri value can contain variables. - - - -Several http3_push directives -can be specified on the same configuration level. -The off parameter cancels the effect -of the http3_push directives -inherited from the previous configuration level. - - - - - - -on | off -off -http -server -location - - -Enables automatic conversion of -preload -links -specified in the

Link

response header fields into -push -requests. - - - - - size 64k @@ -294,21 +218,6 @@ Tokens generated with old keys are not a - -size -65527 -http -server - - -Sets the -QUIC max_udp_payload_size transport parameter value. -This is the maximum UDP payload possible to receive. - - - - - on | off off diff --git a/xml/en/docs/quic.xml b/xml/en/docs/quic.xml --- a/xml/en/docs/quic.xml +++ b/xml/en/docs/quic.xml @@ -7,20 +7,18 @@

+ rev="2">

+Support for QUIC and HTTP/3 -protocols are supported since 1.23.4 and are available -as a separate nginx-quic -prebult Linux package -or as part of our -commercial subscription -in a separate nginx-plus-http3 package. +protocols is available since 1.25.0. +Also, since 1.25.0, the QUIC and HTTP/3 support is available in +Linux binary packages. @@ -32,144 +30,6 @@ The QUIC and HTTP/3 support is experimen

- - -For Linux, nginx-quic packages -from nginx.org can be used. -The packages -are available for the following Linux distributions and -versions: - - - -RHEL 9 and derivatives: amd64, arm64 - - - -Ubuntu 22.04: amd64, arm64 - - - - - - -The nginx-quic packages are dynamically linked with the -QuicTLS library. -It will be installed as a runtime dependency -alongside system-wide OpenSSL packages. -QuicTLS differs from operating system-provided OpenSSL package in the following: - - - -does not follow system-wide crypto policies - - - -does not have distribution-specific patches applied - - - -uses configuration from /etc/pki/quictls (RHEL9) -or /etc/quictls (Ubuntu 22.04) - - - - - - -The nginx-quic packages -cannot be installed alongside nginx or nginx-plus packages. - - - -Please back up your configuration files -before installing nginx-quic: - -sudo cp -a /etc/nginx /etc/nginx-quic-backup - - - - -

- - -The nginx-quic package can be installed on -Red Hat Enterprise Linux and its derivatives such as -CentOS, Oracle Linux, Rocky Linux, AlmaLinux. - - - -Install the prerequisites: - -sudo dnf install yum-utils - - -To set up the yum repository, create the file named -/etc/yum.repos.d/nginx-quic.repo -with the following contents: - - -[nginx-quic] -name=nginx-quic repo -baseurl=https://packages.nginx.org/nginx-quic/rhel/9/$basearch/ -gpgcheck=1 -enabled=1 -gpgkey=https://nginx.org/keys/nginx_signing.key - - -To install nginx-quic, run the following commands: - -sudo dnf install nginx-quic - - -When prompted to accept the GPG key, verify that the fingerprint matches -573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62, -and if so, accept it. - - -

- - -

- - -Install the prerequisites: - -sudo apt update && sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring - - - - -Import an official nginx signing key so apt could verify the packages -authenticity. -Fetch the key: - -curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \ - | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null - - -To set up the apt repository for nginx-quic packages, run the following command: - -echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ - https://packages.nginx.org/nginx-quic/ubuntu `lsb_release -cs` nginx-quic" \ - | sudo tee /etc/apt/sources.list.d/nginx-quic.list - - - - -To install nginx-quic, run the following commands: - -sudo apt update -sudo apt install nginx-quic - - - -

- -

@@ -178,19 +38,9 @@ Please refer to - - ---with-http_v3_module
- - -enables QUIC and HTTP/3. - - - +When configuring nginx, it is possible to enable QUIC and HTTP/3 using the +--with-http_v3_module +configuration parameter. @@ -207,10 +57,12 @@ compatibility layer will be used that do Use the following command to configure nginx with BoringSSL: -./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" +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../boringssl/include" + --with-ld-opt="-L../boringssl/build/ssl + -L../boringssl/build/crypto" @@ -218,9 +70,11 @@ Use the following command to configure n Alternatively, nginx can be configured with QuicTLS: -./auto/configure --with-debug --with-http_v3_module \ - --with-cc-opt="-I../quictls/build/include" \ - --with-ld-opt="-L../quictls/build/lib" +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../quictls/build/include" + --with-ld-opt="-L../quictls/build/lib" @@ -228,9 +82,11 @@ Alternatively, nginx can be configured w Alternatively, nginx can be configured with a modern version of LibreSSL: -./auto/configure --with-debug --with-http_v3_module \ - --with-cc-opt="-I../libressl/build/include" \ - --with-ld-opt="-L../libressl/build/lib" +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../libressl/build/include" + --with-ld-opt="-L../libressl/build/lib" @@ -260,6 +116,11 @@ parameter to make it work properly with +For the list of directives, see +ngx_http_v3_module. + + + To enable address validation: @@ -278,18 +139,11 @@ GSO (Generic Segmentation Offloading): quic_gso on; -To limit -maximum UDP payload size on receive path: - -quic_mtu <size>; - - To set host key for various tokens: quic_host_key <filename>; - @@ -329,7 +183,7 @@ http { ssl_certificate_key certs/example.com.key; location / { - # required for browsers to direct them into quic port + # required for browsers to direct them to quic port add_header Alt-Svc 'h3=":8443"; ma=86400'; } } @@ -340,17 +194,6 @@ http {

- - -For the list of directives, please refer to -ngx_http_v3_module -module documentation. - - -

- -

@@ -358,7 +201,7 @@ Tips that may help to identify problems: -Ensure nginx is built with the proper SSL library that supports QUIC. +Ensure nginx is built with the proper SSL library. @@ -368,7 +211,7 @@ Ensure nginx is using the proper SSL lib Ensure a client is actually sending requests over QUIC. -We recommend starting with a simple console client such as +It is recommended to start with a simple console client such as ngtcp2 to ensure the server is configured properly before trying with real browsers that may be quite picky with certificates. @@ -383,16 +226,20 @@ and can be easily filtered out. -For a deeper investigation, please enable additional debugging in -src/event/quic/ngx_event_quic_connection.h: +For a deeper investigation, additional debugging can be enabled +using the following macros: +NGX_QUIC_DEBUG_PACKETS, +NGX_QUIC_DEBUG_FRAMES, +NGX_QUIC_DEBUG_ALLOC, +NGX_QUIC_DEBUG_CRYPTO. - -#define NGX_QUIC_DEBUG_PACKETS -#define NGX_QUIC_DEBUG_FRAMES -#define NGX_QUIC_DEBUG_ALLOC -#define NGX_QUIC_DEBUG_CRYPTO - + +./configure + --with-http_v3_module + --with-debug + --with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO" + @@ -401,13 +248,4 @@ For a deeper investigation, please enabl

- -

- - -Please refer to . - - -

diff --git a/xml/ru/GNUmakefile b/xml/ru/GNUmakefile --- a/xml/ru/GNUmakefile +++ b/xml/ru/GNUmakefile @@ -19,6 +19,7 @@ DOCS = \ contributing_changes \ beginners_guide \ configure \ + quic \ FAQ = \ sys_errlist \ diff --git a/xml/ru/docs/configure.xml b/xml/ru/docs/configure.xml --- a/xml/ru/docs/configure.xml +++ b/xml/ru/docs/configure.xml @@ -8,7 +8,7 @@

+ rev="21">

@@ -236,7 +236,7 @@ По умолчанию модуль не собирается. - + --with-http_v3_module

diff --git a/xml/ru/docs/http/ngx_http_core_module.xml b/xml/ru/docs/http/ngx_http_core_module.xml --- a/xml/ru/docs/http/ngx_http_core_module.xml +++ b/xml/ru/docs/http/ngx_http_core_module.xml @@ -10,7 +10,7 @@ + rev="104">

@@ -1382,7 +1382,7 @@ HTTP/2-соединений без SSL. -Параметр quic (1.23.4) позволяет принимать на этом порту +Параметр quic (1.25.0) позволяет принимать на этом порту QUIC-соединения. diff --git a/xml/ru/docs/http/ngx_http_v3_module.xml b/xml/ru/docs/http/ngx_http_v3_module.xml --- a/xml/ru/docs/http/ngx_http_v3_module.xml +++ b/xml/ru/docs/http/ngx_http_v3_module.xml @@ -9,12 +9,12 @@ + rev="2">

-Модуль ngx_http_v3_module (1.23.4) обеспечивает +Модуль ngx_http_v3_module (1.25.0) обеспечивает экспериментальную поддержку HTTP/3. @@ -22,7 +22,7 @@ По умолчанию этот модуль не собирается, его сборку необходимо разрешить с помощью конфигурационного параметра ---with-http_v3_module. +--with-http_v3_module. Для сборки и работы этого модуля рекомендуется использовать библиотеку SSL с поддержкой QUIC, например @@ -37,18 +37,6 @@ - - -Модуль доступен в виде -готовых пакетов -nginx-quic для Linux. -Модуль также доступен как часть -коммерческой подписки -в виде отдельного пакета nginx-plus-quic. - - - -

@@ -129,20 +117,6 @@ http { - -число -10 -http -server - - -Ограничивает максимальное число параллельных -push-запросов в соединении. - - - - - число 128 @@ -157,55 +131,6 @@ http { - -uri | off -off -http -server -location - - -Заблаговременно отправляет -(push) запрос -к заданному uri -вместе с ответом на оригинальный запрос. -Будут обработаны только относительные URI с абсолютными путями, -например: - -http3_push /static/css/main.css; - -В значении uri допустимо использование переменных. - - - -На одном уровне конфигурации можно указать несколько -http3_push директив. -Параметр off отменяет действие -унаследованных с предыдущего уровня конфигурации -директив http3_push. - - - - - - -on | off -off -http -server -location - - -Разрешает автоматическое преобразование -preload -links, -указанных в полях

Link

заголовка ответа, в -push-запросы. - - - - - размер 64k @@ -293,21 +218,6 @@ stateless reset и address validation токенов. - -размер -65527 -http -server - - -Устанавливает -значение транспортного параметра QUIC max_udp_payload_size. -Это максимально возможное значение для получения UDP payload. - - - - - on | off off diff --git a/xml/ru/docs/index.xml b/xml/ru/docs/index.xml --- a/xml/ru/docs/index.xml +++ b/xml/ru/docs/index.xml @@ -66,7 +66,7 @@ -Поддержка QUIC и HTTP/3 [en] + diff --git a/xml/ru/docs/quic.xml b/xml/ru/docs/quic.xml new file mode 100644 --- /dev/null +++ b/xml/ru/docs/quic.xml @@ -0,0 +1,254 @@ + + + + +

+ +

+ + +Поддержка протоколов +QUIC +и +HTTP/3 +доступна начиная с версии 1.25.0. +Также, начиная с 1.25.0, поддержка доступна в +готовых пакетах для Linux. + + + + +Поддержка QUIC и HTTP/3 экспериментальная, поэтому возможно всё. + + + +

+ + +

+ + +Сборка настраивается командой configure. +Подробнее см. в статье . + + + +Во время сборки nginx можно включить QUIC и HTTP/3 +при помощи конфигурационного параметра +--with-http_v3_module. + + + +Для сборки nginx рекомендуется библиотека SSL с поддержкой QUIC, например +BoringSSL, +LibreSSL или +QuicTLS. +Иначе, при использовании библиотеки OpenSSL, +будет использоваться OpenSSL compatibility layer, в котором не поддерживается +early data. + + + +При конфигурации nginx с +BoringSSL +используется следующая команда: + +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../boringssl/include" + --with-ld-opt="-L../boringssl/build/ssl + -L../boringssl/build/crypto" + + + + +Кроме того, можно сконфигурировать nginx с +QuicTLS: + +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../quictls/build/include" + --with-ld-opt="-L../quictls/build/lib" + + + + +Кроме того, можно сконфигурировать nginx с современной версией +LibreSSL: + +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../libressl/build/include" + --with-ld-opt="-L../libressl/build/lib" + + + + +После конфигурации +nginx компилируется и устанавливается с помощью +make. + + +

+ + +

+ + +В директиве +модуля ngx_http_core_module +появился новый параметр +quic, +который позволяет принимать на указанном порту QUIC-соединения. + + + +Вместе с параметром quic +можно также указать параметр +reuseport +для правильной работы с несколькими рабочими процессами. + + + +Список директив см. в модуле +ngx_http_v3_module. + + + +Чтобы разрешить +проверку адреса: + +quic_retry on; + + +Чтобы разрешить +0-RTT: + +ssl_early_data on; + + +Чтобы разрешить +GSO (Generic Segmentation Offloading): + +quic_gso on; + + +Чтобы установить +host-ключ для различных токенов: + +quic_host_key <filename>; + + + + +Для работы QUIC требуется версия протокла TLSv1.3, которая включена по умолчанию +в директиве . + + + +По умолчанию +GSO Linux-specific optimization +выключена. +Включите, если настроен соответствующий сетевой интерфейс, +поддерживающий GSO. + + +

+ + +

+ + + +http { + log_format quic '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $body_bytes_sent ' + '"$http_referer" "$http_user_agent" "$http3"'; + + access_log logs/access.log quic; + + server { + # для лучшей совместимости рекомендуется + # использовать один порт для quic и https + listen 8443 quic reuseport; + listen 8443 ssl; + + ssl_certificate certs/example.com.crt; + ssl_certificate_key certs/example.com.key; + + location / { + # для перенаправления браузеров в quic-порт + add_header Alt-Svc 'h3=":8443"; ma=86400'; + } + } +} + + + +

+ + +

+ + +Приблизительные шаги при обнаружении проблемы: + + + +Убедитесь, что nginx собран с правильной SSL-библиотекой. + + + +Убедитесь, что nginx использует правильную SSL-библиотеку в runtime +(nginx -V покажет что именно используется в данный момент). + + + +Убедитесь, что клиент действительно присылает запросы через QUIC. +Рекомендуется начать с простого консольного клиента, например +ngtcp2, +чтобы убедиться, что сервер настроен правильно, и затем попробовать +в браузерах, так как браузеры могут быть требовательны к сертификатам. + + + +Соберите nginx с поддержкой отладочного лога +и проверьте отладочный лог. +В нём должны содержаться все детали соединения и причины ошибок. +Соответствующие сообщения начинаются с префикса “quic” +и могут быть по нему отфильтрованы. + + + +Для детального исследования можно включить дополнительную отладку +при помощи следующих макросов: +NGX_QUIC_DEBUG_PACKETS, +NGX_QUIC_DEBUG_FRAMES, +NGX_QUIC_DEBUG_ALLOC, +NGX_QUIC_DEBUG_CRYPTO. + + + +./configure + --with-http_v3_module + --with-debug + --with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO" + + + + + + + + +

+ +