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

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

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

Сборка из исходного кода

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

Для сборки nginx с поддержкой QUIC рекомендуется библиотека OpenSSL версии 3.5.1 или выше. В противном случае будет использоваться уровень совместимости OpenSSL, который не поддерживает ранние данные. Также можно использовать предварительно собранные библиотеки 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, который включает HTTP/3 поверх QUIC на указанном порту.

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

Чтобы включить проверку адреса:

quic_retry on;

Чтобы включить 0-RTT:

ssl_early_data on;

Чтобы включить GSO (обобщённую разгрузку сегментации):

quic_gso on;

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

quic_host_key <filename>;

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

По умолчанию оптимизация GSO, специфичная для Linux, отключена. Включите её, если соответствующий сетевой интерфейс настроен для поддержки GSO.

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

Советы, которые могут помочь выявить проблемы:

• Убедитесь, что nginx собран с подходящей библиотекой SSL.
• Убедитесь, что nginx использует подходящую библиотеку SSL во время выполнения (команда 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"