🔥 Breaking News: ru/docs/quic.html

Поддержка QUIC и HTTP/3

Сборка из исходных файлов
Советы по настройке
Устранение неполадок

Поддержка протоколов QUIC и HTTP/3 доступна начиная с версии 1.25.0, она включена в бинарных пакетах для Linux. Подробнее см. документацию к модулю ngx_http_v3_module.

Сборка из исходных файлов

Сборка настраивается командой configure. Подробнее см. в статье Сборка nginx из исходных файлов.

Для сборки nginx с поддержкой QUIC рекомендуется библиотека OpenSSL версии 3.5.1 или выше. Иначе будет использоваться OpenSSL compatibility layer без поддержки TLS early data. Также возможно использование предварительно собранной библиотеки BoringSSL, LibreSSL или QuicTLS.

При конфигурации nginx с BoringSSL используется следующая команда:

./configure
    --with-debug
    --with-http_v3_module
    --with-cc-opt="-I../boringssl/include"
    --with-ld-opt="-L../boringssl/build -lstdc++"

Кроме того, можно сконфигурировать 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.

Советы по настройке

В директиве listen модуля ngx_http_core_module появился новый параметр quic, который позволяет принимать на указанном порту QUIC-соединения.

Вместе с параметром quic можно также указать параметр reuseport для правильной работы с несколькими рабочими процессами.

Чтобы разрешить проверку адреса:

quic_retry on;

Чтобы разрешить 0-RTT:

ssl_early_data on;

Чтобы разрешить GSO (Generic Segmentation Offloading):

quic_gso on;

Чтобы установить host-ключ для различных токенов:

quic_host_key <filename>;

Для работы QUIC требуется версия протокла TLSv1.3, которая включена по умолчанию в директиве ssl_protocols.

По умолчанию GSO Linux-specific optimization выключена. Включите, если настроен соответствующий сетевой интерфейс, поддерживающий GSO.

Устранение неполадок

Приблизительные шаги при обнаружении проблемы:

Убедитесь, что 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"
```