xml/en/docs/configure.xml | 4 +-
xml/en/docs/http/ngx_http_core_module.xml | 4 +-
xml/en/docs/http/ngx_http_v3_module.xml | 97 +-----------
xml/en/docs/quic.xml | 248 +++++------------------------
xml/ru/GNUmakefile | 1 +
xml/ru/docs/configure.xml | 4 +-
xml/ru/docs/http/ngx_http_core_module.xml | 4 +-
xml/ru/docs/http/ngx_http_v3_module.xml | 96 +-----------
xml/ru/docs/index.xml | 2 +-
xml/ru/docs/quic.xml | 252 ++++++++++++++++++++++++++++++
10 files changed, 310 insertions(+), 402 deletions(-)
# HG changeset patch
# User Yaroslav Zhuravlev <y...@nginx.com>
# Date 1684852637 -3600
# Tue May 23 15:37:17 2023 +0100
# Node ID 9015546a429e45497c7d189e0f3a77423254e019
# Parent c7bf5c9a1174695b7505b8d1b7a94fe6abff318f
Updated QUIC documentation after QUIC code merge.
- removed http3_max_concurrent_pushes, http3_push
http3_push_preload, quic_mtu
- updated apperared-in version
- update of quic.xml, adding Rus translation
diff --git a/xml/en/docs/configure.xml b/xml/en/docs/configure.xml
--- a/xml/en/docs/configure.xml
+++ b/xml/en/docs/configure.xml
@@ -8,7 +8,7 @@
<article name="Building nginx from Sources"
link="/en/docs/configure.html"
lang="en"
- rev="20">
+ rev="21">
<section>
@@ -238,7 +238,7 @@
This module is not built by default.
</tag-desc>
-<tag-name>
+<tag-name id="http_v3_module">
<literal>--with-http_v3_module</literal>
</tag-name>
<tag-desc>
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 @@
<module name="Module ngx_http_core_module"
link="/en/docs/http/ngx_http_core_module.html"
lang="en"
- rev="103">
+ rev="104">
<section id="directives" name="Directives">
@@ -1390,7 +1390,7 @@
</para>
<para id="quic">
-The <literal>quic</literal> parameter (1.23.4) configures the port to accept
+The <literal>quic</literal> parameter (1.25.0) configures the port to accept
<link doc="ngx_http_v3_module.xml">QUIC</link> connections.
</para>
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 @@
<module name="Module ngx_http_v3_module"
link="/en/docs/http/ngx_http_v3_module.html"
lang="en"
- rev="1">
+ rev="2">
<section id="summary">
<para>
-The <literal>ngx_http_v3_module</literal> module (1.23.4) provides
+The <literal>ngx_http_v3_module</literal> module (1.25.0) provides
experimental support for
<link url="https://datatracker.ietf.org/doc/html/rfc9114";>HTTP/3</link>.
</para>
<para>
This module is not built by default, it should be enabled with the
-<link doc="../configure.xml"><literal>--with-http_v3_module</literal></link>
+<link doc="../configure.xml" id="http_v3_module"><literal>--with-http_v3_module</literal></link>
configuration parameter.
<note>
An SSL library that provides QUIC support
@@ -37,18 +37,6 @@
</note>
</para>
-
-<para>
-<note>
-The module is available as
-<literal>nginx-quic</literal> in
-<link doc="../quic.xml" id="linux">prebult Linux packages</link>.
-The module is also available as part of our
-<commercial_version>commercial subscription</commercial_version>
-in a separate <literal>nginx-plus-quic</literal> package.
-</note>
-</para>
-
</section>
@@ -129,20 +117,6 @@
</directive>
-<directive name="http3_max_concurrent_pushes">
-<syntax><value>number</value></syntax>
-<default>10</default>
-<context>http</context>
-<context>server</context>
-
-<para>
-Limits the maximum number of concurrent
-<link id="http3_push">push</link> requests in a connection.
-</para>
-
-</directive>
-
-
<directive name="http3_max_concurrent_streams">
<syntax><value>number</value></syntax>
<default>128</default>
@@ -157,56 +131,6 @@
</directive>
-<directive name="http3_push">
-<syntax><value>uri</value> | <literal>off</literal></syntax>
-<default>off</default>
-<context>http</context>
-<context>server</context>
-<context>location</context>
-
-<para>
-Pre-emptively sends
-(<link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push";>pushes</link>)
-a request to the specified <value>uri</value>
-along with the response to the original request.
-Only relative URIs with absolute path will be processed,
-for example:
-<example>
-http3_push /static/css/main.css;
-</example>
-The <value>uri</value> value can contain variables.
-</para>
-
-<para>
-Several <literal>http3_push</literal> directives
-can be specified on the same configuration level.
-The <literal>off</literal> parameter cancels the effect
-of the <literal>http3_push</literal> directives
-inherited from the previous configuration level.
-</para>
-
-</directive>
-
-
-<directive name="http3_push_preload">
-<syntax><literal>on</literal> | <literal>off</literal></syntax>
-<default>off</default>
-<context>http</context>
-<context>server</context>
-<context>location</context>
-
-<para>
-Enables automatic conversion of
-<link url="https://www.w3.org/TR/preload/#server-push-http-3";>preload
-links</link>
-specified in the <header>Link</header> response header fields into
-<link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push";>push</link>
-requests.
-</para>
-
-</directive>
-
-
<directive name="http3_stream_buffer_size">
<syntax><value>size</value></syntax>
<default>64k</default>
@@ -294,21 +218,6 @@
</directive>
-<directive name="quic_mtu">
-<syntax><value>size</value></syntax>
-<default>65527</default>
-<context>http</context>
-<context>server</context>
-
-<para>
-Sets the
-QUIC <literal>max_udp_payload_size</literal> transport parameter value.
-This is the maximum UDP payload possible to receive.
-</para>
-
-</directive>
-
-
<directive name="quic_retry">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
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,16 @@
<article name="Support for QUIC and HTTP/3"
link="/en/docs/quic.html"
lang="en"
- rev="1">
+ rev="2">
<section>
<para>
+Support for
<link url="https://datatracker.ietf.org/doc/html/rfc9000";>QUIC</link>
and
<link url="https://datatracker.ietf.org/doc/html/rfc9114";>HTTP/3</link>
-protocols are supported since 1.23.4 and are available
-as a separate <literal>nginx-quic</literal>
-<link id="linux">prebult Linux package</link>
-or as part of our
-<commercial_version>commercial subscription</commercial_version>
-in a separate <literal>nginx-plus-http3</literal> package.
+protocols is available since 1.25.0.
</para>
<para>
@@ -32,144 +28,6 @@
</section>
-<section id="linux" name="Installation on Linux">
-
-<para>
-For Linux, <literal>nginx-quic</literal> packages
-from nginx.org can be used.
-The packages
-are available for the following Linux distributions and
-versions:
-<list type="bullet">
-
-<listitem>
-<link id="rhel">RHEL 9 and derivatives</link>: amd64, arm64
-</listitem>
-
-<listitem>
-<link id="rhel">Ubuntu 22.04</link>: amd64, arm64
-</listitem>
-
-</list>
-</para>
-
-<para>
-The <literal>nginx-quic</literal> packages are dynamically linked with the
-<link url="https://github.com/quictls/openssl";>QuicTLS</link> 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:
-<list type="bullet">
-
-<listitem>
-does not follow system-wide crypto policies
-</listitem>
-
-<listitem>
-does not have distribution-specific patches applied
-</listitem>
-
-<listitem>
-uses configuration from <literal>/etc/pki/quictls</literal> (RHEL9)
-or <literal>/etc/quictls</literal> (Ubuntu 22.04)
-</listitem>
-
-</list>
-</para>
-
-<para>
-The <literal>nginx-quic</literal> packages
-cannot be installed alongside nginx or nginx-plus packages.
-</para>
-
-<para>
-Please back up your configuration files
-before installing <literal>nginx-quic</literal>:
-<programlisting>
-sudo cp -a /etc/nginx /etc/nginx-quic-backup
-</programlisting>
-</para>
-
-
-<section name="RHEL" id="rhel">
-
-<para>
-The <literal>nginx-quic</literal> package can be installed on
-Red Hat Enterprise Linux and its derivatives such as
-CentOS, Oracle Linux, Rocky Linux, AlmaLinux.
-</para>
-
-<para>
-Install the prerequisites:
-<programlisting>
-sudo dnf install yum-utils
-</programlisting>
-
-To set up the yum repository, create the file named
-<path>/etc/yum.repos.d/nginx-quic.repo </path>
-with the following contents:
-
-<programlisting>
-[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
-</programlisting>
-
-To install nginx-quic, run the following commands:
-<programlisting>
-sudo dnf install nginx-quic
-</programlisting>
-
-When prompted to accept the GPG key, verify that the fingerprint matches
-<command>573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62</command>,
-and if so, accept it.
-</para>
-
-</section>
-
-
-<section name="Ubuntu" id="ubuntu">
-
-<para>
-Install the prerequisites:
-<programlisting>
-sudo apt update && sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring
-</programlisting>
-</para>
-
-<para>
-Import an official nginx signing key so apt could verify the packages
-authenticity.
-Fetch the key:
-<programlisting>
-curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
- | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
-</programlisting>
-
-To set up the apt repository for nginx-quic packages, run the following command:
-<programlisting>
-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
-</programlisting>
-</para>
-
-<para>
-To install nginx-quic, run the following commands:
-<programlisting>
-sudo apt update
-sudo apt install nginx-quic
-</programlisting>
-</para>
-
-</section>
-
-</section>
-
-
<section id="building" name="Building from sources">
<para>
@@ -178,19 +36,9 @@
</para>
<para>
-When configuring nginx, it is possible to enable QUIC and HTTP/3
-using the following configuration options:
-
-<list type="tag">
-
-<tag-name>
-<literal>--with-http_v3_module</literal><br/>
-</tag-name>
-<tag-desc>
-enables QUIC and HTTP/3.
-</tag-desc>
-
-</list>
+When configuring nginx, it is possible to enable QUIC and HTTP/3 using the
+<link doc="configure.xml" id="http_v3_module"><literal>--with-http_v3_module</literal></link>
+configuration parameter.
</para>
<para>
@@ -207,10 +55,12 @@
Use the following command to configure nginx with
<link url="https://boringssl.googlesource.com/boringssl";>BoringSSL</link>:
<programlisting>
-./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"
</programlisting>
</para>
@@ -218,9 +68,11 @@
Alternatively, nginx can be configured with
<link url="https://github.com/quictls/openssl";>QuicTLS</link>:
<programlisting>
-./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"
</programlisting>
</para>
@@ -228,9 +80,11 @@
Alternatively, nginx can be configured with a modern version of
<link url="https://www.libressl.org";>LibreSSL</link>:
<programlisting>
-./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"
</programlisting>
</para>
@@ -260,6 +114,11 @@
</para>
<para>
+For the list of directives, see
+<link doc="http/ngx_http_v3_module.xml">ngx_http_v3_module</link>.
+</para>
+
+<para>
To <link doc="http/ngx_http_v3_module.xml" id="quic_retry">enable</link>
address validation:
<programlisting>
@@ -278,18 +137,11 @@
quic_gso on;
</programlisting>
-To <link doc="http/ngx_http_v3_module.xml" id="quic_mtu">limit</link>
-maximum UDP payload size on receive path:
-<programlisting>
-quic_mtu <size>;
-</programlisting>
-
To <link doc="http/ngx_http_v3_module.xml" id="quic_host_key">set</link>
host key for various tokens:
<programlisting>
quic_host_key <filename>;
</programlisting>
-
</para>
<para>
@@ -329,7 +181,7 @@
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 +192,6 @@
</section>
-<section id="directives" name="Directives">
-
-<para>
-For the list of directives, please refer to
-<link doc="http/ngx_http_v3_module.xml">ngx_http_v3_module</link>
-module documentation.
-</para>
-
-</section>
-
-
<section id="troubleshooting " name="Troubleshooting">
<para>
@@ -358,7 +199,7 @@
<list type="bullet">
<listitem>
-Ensure nginx is built with the proper SSL library that supports QUIC.
+Ensure nginx is built with the proper SSL library.
</listitem>
<listitem>
@@ -368,7 +209,7 @@
<listitem>
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
<link url="https://nghttp2.org/ngtcp2";>ngtcp2</link>
to ensure the server is configured properly before trying
with real browsers that may be quite picky with certificates.
@@ -383,16 +224,20 @@
</listitem>
<listitem>
-For a deeper investigation, please enable additional debugging in
-<literal>src/event/quic/ngx_event_quic_connection.h</literal>:
+For a deeper investigation, additional debugging can be enabled
+using the following macros:
+<literal>NGX_QUIC_DEBUG_PACKETS</literal>,
+<literal>NGX_QUIC_DEBUG_FRAMES</literal>,
+<literal>NGX_QUIC_DEBUG_ALLOC</literal>,
+<literal>NGX_QUIC_DEBUG_CRYPTO</literal>.
<para>
-<example>
-#define NGX_QUIC_DEBUG_PACKETS
-#define NGX_QUIC_DEBUG_FRAMES
-#define NGX_QUIC_DEBUG_ALLOC
-#define NGX_QUIC_DEBUG_CRYPTO
-</example>
+<programlisting>
+./configure
+ --with-http_v3_module
+ --with-debug
+ --with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO"
+</programlisting>
</para>
</listitem>
@@ -401,13 +246,4 @@
</section>
-
-<section id="contributing" name="Contributing">
-
-<para>
-Please refer to <link doc="contributing_changes.xml"/>.
-</para>
-
-</section>
-
</article>
diff --git a/xml/ru/GNUmakefile b/xml/ru/GNUmakefile
--- a/xml/ru/GNUmakefile
+++ b/xml/ru/GNUmakefile
@@ -19,6 +19,7 @@
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 @@
<article name="Сборка nginx из исходных файлов"
link="/ru/docs/configure.html"
lang="ru"
- rev="20">
+ rev="21">
<section>
@@ -236,7 +236,7 @@
По умолчанию модуль не собирается.
</tag-desc>
-<tag-name>
+<tag-name id="http_v3_module">
<literal>--with-http_v3_module</literal>
</tag-name>
<tag-desc>
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 @@
<module name="Модуль ngx_http_core_module"
link="/ru/docs/http/ngx_http_core_module.html"
lang="ru"
- rev="103">
+ rev="104">
<section id="directives" name="Директивы">
@@ -1382,7 +1382,7 @@
</para>
<para id="quic">
-Параметр <literal>quic</literal> (1.23.4) позволяет принимать на этом порту
+Параметр <literal>quic</literal> (1.25.0) позволяет принимать на этом порту
<link doc="ngx_http_v3_module.xml">QUIC</link>-соединения.
</para>
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 @@
<module name="Модуль ngx_http_v3_module"
link="/ru/docs/http/ngx_http_v3_module.html"
lang="en"
- rev="1">
+ rev="2">
<section id="summary">
<para>
-Модуль <literal>ngx_http_v3_module</literal> (1.23.4) обеспечивает
+Модуль <literal>ngx_http_v3_module</literal> (1.25.0) обеспечивает
экспериментальную поддержку
<link url="https://datatracker.ietf.org/doc/html/rfc9114";>HTTP/3</link>.
</para>
@@ -22,7 +22,7 @@
<para>
По умолчанию этот модуль не собирается, его сборку необходимо
разрешить с помощью конфигурационного параметра
-<link doc="../configure.xml"><literal>--with-http_v3_module</literal></link>.
+<link doc="../configure.xml" id="http_v3_module"><literal>--with-http_v3_module</literal></link>.
<note>
Для сборки и работы этого модуля рекомендуется использовать
библиотеку SSL с поддержкой QUIC, например
@@ -37,18 +37,6 @@
</note>
</para>
-<para>
-<note>
-Модуль доступен в виде
-<link doc="../quic.xml" id="linux">готовых пакетов</link>
-<literal>nginx-quic</literal> для Linux.
-Модуль также доступен как часть
-<commercial_version>коммерческой подписки</commercial_version>
-в виде отдельного пакета <literal>nginx-plus-quic</literal>.
-
-</note>
-</para>
-
</section>
@@ -129,20 +117,6 @@
</directive>
-<directive name="http3_max_concurrent_pushes">
-<syntax><value>число</value></syntax>
-<default>10</default>
-<context>http</context>
-<context>server</context>
-
-<para>
-Ограничивает максимальное число параллельных
-<link id="http3_push">push</link>-запросов в соединении.
-</para>
-
-</directive>
-
-
<directive name="http3_max_concurrent_streams">
<syntax><value>число</value></syntax>
<default>128</default>
@@ -157,55 +131,6 @@
</directive>
-<directive name="http3_push">
-<syntax><value>uri</value> | <literal>off</literal></syntax>
-<default>off</default>
-<context>http</context>
-<context>server</context>
-<context>location</context>
-
-<para>
-Заблаговременно отправляет
-(<link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push";>push</link>) запрос
-к заданному <value>uri</value>
-вместе с ответом на оригинальный запрос.
-Будут обработаны только относительные URI с абсолютными путями,
-например:
-<example>
-http3_push /static/css/main.css;
-</example>
-В значении <value>uri</value> допустимо использование переменных.
-</para>
-
-<para>
-На одном уровне конфигурации можно указать несколько
-<literal>http3_push</literal> директив.
-Параметр <literal>off</literal> отменяет действие
-унаследованных с предыдущего уровня конфигурации
-директив <literal>http3_push</literal>.
-</para>
-
-</directive>
-
-
-<directive name="http3_push_preload">
-<syntax><literal>on</literal> | <literal>off</literal></syntax>
-<default>off</default>
-<context>http</context>
-<context>server</context>
-<context>location</context>
-
-<para>
-Разрешает автоматическое преобразование
-<link url="https://www.w3.org/TR/preload/#server-push-http-3";>preload
-links</link>,
-указанных в полях <header>Link</header> заголовка ответа, в
-<link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push";>push</link>-запросы.
-</para>
-
-</directive>
-
-
<directive name="http3_stream_buffer_size">
<syntax><value>размер</value></syntax>
<default>64k</default>
@@ -293,21 +218,6 @@
</directive>
-<directive name="quic_mtu">
-<syntax><value>размер</value></syntax>
-<default>65527</default>
-<context>http</context>
-<context>server</context>
-
-<para>
-Устанавливает
-значение транспортного параметра QUIC <literal>max_udp_payload_size</literal>.
-Это максимально возможное значение для получения UDP payload.
-</para>
-
-</directive>
-
-
<directive name="quic_retry">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
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 @@
</listitem>
<listitem>
-<link doc="../../en/docs/quic.xml">Поддержка QUIC и HTTP/3</link> [en]
+<link doc="quic.xml"/>
</listitem>
</list>
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,252 @@
+<!--
+ Copyright (C) Nginx, Inc.
+ -->
+
+<!DOCTYPE article SYSTEM "../../../dtd/article.dtd">
+
+<article name="Поддержка QUIC и HTTP/3"
+ link="/ru/docs/quic.html"
+ lang="ru"
+ rev="2">
+
+<section>
+
+<para>
+Поддержка протоколов
+<link url="https://datatracker.ietf.org/doc/html/rfc9000";>QUIC</link>
+и
+<link url="https://datatracker.ietf.org/doc/html/rfc9114";>HTTP/3</link>
+доступна начиная с версии 1.25.0.
+</para>
+
+<para>
+<note>
+Поддержка QUIC и HTTP/3 экспериментальная, поэтому возможно всё.
+</note>
+</para>
+
+</section>
+
+
+<section id="building" name="Сборка из исходных файлов">
+
+<para>
+Сборка настраивается командой <command>configure</command>.
+Подробнее см. в статье <link doc="configure.xml"/>.
+</para>
+
+<para>
+Во время сборки nginx можно включить QUIC и HTTP/3
+при помощи конфигурационного параметра
+<link doc="configure.xml" id="http_v3_module"><literal>--with-http_v3_module</literal></link>.
+</para>
+
+<para>
+Для сборки nginx рекомендуется библиотека SSL с поддержкой QUIC, например
+<link url="https://boringssl.googlesource.com/boringssl";>BoringSSL</link>,
+<link url="https://www.libressl.org";>LibreSSL</link> или
+<link url="https://github.com/quictls/openssl";>QuicTLS</link>.
+Иначе, при использовании библиотеки <link url="https://openssl.org";>OpenSSL</link>,
+будет использоваться OpenSSL compatibility layer, в котором не поддерживается
+<link doc="http/ngx_http_ssl_module.xml" id="ssl_early_data">early data</link>.
+</para>
+
+<para>
+При конфигурации nginx с
+<link url="https://boringssl.googlesource.com/boringssl";>BoringSSL</link>
+используется следующая команда:
+<programlisting>
+./configure
+ --with-debug
+ --with-http_v3_module
+ --with-cc-opt="-I../boringssl/include"
+ --with-ld-opt="-L../boringssl/build/ssl
+ -L../boringssl/build/crypto"
+</programlisting>
+</para>
+
+<para>
+Кроме того, можно сконфигурировать nginx с
+<link url="https://github.com/quictls/openssl";>QuicTLS</link>:
+<programlisting>
+./configure
+ --with-debug
+ --with-http_v3_module
+ --with-cc-opt="-I../quictls/build/include"
+ --with-ld-opt="-L../quictls/build/lib"
+</programlisting>
+</para>
+
+<para>
+Кроме того, можно сконфигурировать nginx с современной версией
+<link url="https://www.libressl.org";>LibreSSL</link>:
+<programlisting>
+./configure
+ --with-debug
+ --with-http_v3_module
+ --with-cc-opt="-I../libressl/build/include"
+ --with-ld-opt="-L../libressl/build/lib"
+</programlisting>
+</para>
+
+<para>
+После конфигурации
+nginx компилируется и устанавливается с помощью
+<command>make</command>.
+</para>
+
+</section>
+
+
+<section id="configuration" name="Конфигурация">
+
+<para>
+В директиве <link doc="http/ngx_http_core_module.xml" id="listen"/>
+модуля <link doc="http/ngx_http_core_module.xml">ngx_http_core_module</link>
+появился новый параметр
+<link doc="http/ngx_http_core_module.xml" id="quic">quic</link>,
+который позволяет принимать на указанном порту QUIC-соединения.
+</para>
+
+<para>
+Вместе с параметром <literal>quic</literal>
+можно также указать параметр
+<link doc="http/ngx_http_core_module.xml" id="reuseport">reuseport</link>
+для правильной работы с несколькими рабочими процессами.
+</para>
+
+<para>
+Список директив см. в модуле
+<link doc="http/ngx_http_v3_module.xml">ngx_http_v3_module</link>.
+</para>
+
+<para>
+Чтобы <link doc="http/ngx_http_v3_module.xml" id="quic_retry">разрешить</link>
+проверку адреса:
+<programlisting>
+quic_retry on;
+</programlisting>
+
+Чтобы <link doc="http/ngx_http_ssl_module.xml" id="ssl_early_data">разрешить</link>
+0-RTT:
+<programlisting>
+ssl_early_data on;
+</programlisting>
+
+Чтобы <link doc="http/ngx_http_v3_module.xml" id="quic_gso">разрешить</link>
+GSO (Generic Segmentation Offloading):
+<programlisting>
+quic_gso on;
+</programlisting>
+
+Чтобы <link doc="http/ngx_http_v3_module.xml" id="quic_host_key">установить</link>
+host-ключ для различных токенов:
+<programlisting>
+quic_host_key <filename>;
+</programlisting>
+</para>
+
+<para>
+Для работы QUIC требуется версия протокла TLSv1.3, которая включена по умолчанию
+в директиве <link doc="http/ngx_http_ssl_module.xml" id="ssl_protocols"/>.
+</para>
+
+<para>
+По умолчанию
+<link url="http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf";>GSO Linux-specific optimization</link>
+выключена.
+Включите, если настроен соответствующий сетевой интерфейс,
+поддерживающий GSO.
+</para>
+
+</section>
+
+
+<section id="example" name="Пример конфигурации">
+
+<para>
+<example>
+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';
+ }
+ }
+}
+</example>
+</para>
+
+</section>
+
+
+<section id="troubleshooting " name="Устранение неполадок">
+
+<para>
+Приблизительные шаги при обнаружении проблемы:
+<list type="bullet">
+
+<listitem>
+Убедитесь, что nginx собран с правильной SSL-библиотекой.
+</listitem>
+
+<listitem>
+Убедитесь, что nginx использует правильную SSL-библиотеку в runtime
+(<literal>nginx -V</literal> покажет что именно используется в данный момент).
+</listitem>
+
+<listitem>
+Убедитесь, что клиент действительно присылает запросы через QUIC.
+Рекомендуется начать с простого консольного клиента, например
+<link url="https://nghttp2.org/ngtcp2";>ngtcp2</link>,
+чтобы убедиться, что сервер настроен правильно, и затем попробовать
+в браузерах, так как браузеры могут быть требовательны к сертификатам.
+</listitem>
+
+<listitem>
+Соберите nginx с поддержкой <link doc="debugging_log.xml">отладочного лога</link>
+и проверьте отладочный лог.
+В нём должны содержаться все детали соединения и причины ошибок.
+Соответствующие сообщения начинаются с префикса “<literal>quic</literal>”
+и могут быть по нему отфильтрованы.
+</listitem>
+
+<listitem>
+Для детального исследования можно включить дополнительную отладку
+при помощи следующих макросов:
+<literal>NGX_QUIC_DEBUG_PACKETS</literal>,
+<literal>NGX_QUIC_DEBUG_FRAMES</literal>,
+<literal>NGX_QUIC_DEBUG_ALLOC</literal>,
+<literal>NGX_QUIC_DEBUG_CRYPTO</literal>.
+
+<para>
+<programlisting>
+./configure
+ --with-http_v3_module
+ --with-debug
+ --with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO"
+</programlisting>
+</para>
+
+</listitem>
+
+</list>
+</para>
+
+</section>
+
+</article>
_______________________________________________
nginx-devel mailing list
nginx-devel@nginx.org
https://mailman.nginx.org/mailman/listinfo/nginx-devel
