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

• Компиляция из исходного кода
• Настройка
• Пример конфигурации
• Отладка

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

Поддержка QUIC и HTTP/3 находится в экспериментальной стадии, соблюдайте осторожность.

Компиляция из исходного кода

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

При конфигурации nginx можно включить QUIC и HTTP/3, используя параметр конфигурации --with-http_v3_module.

Для компиляции nginx рекомендуется использовать библиотеку SSL, поддерживающую QUIC, такую как BoringSSL, LibreSSL или QuicTLS. В противном случае будет использоваться совместимый слой OpenSSL, который не поддерживает ранние данные.

Используйте следующую команду для конфигурации 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.

Настройка

Директива listen в модуле ngx_http_core_module получила новый параметр quic, который включает HTTP/3 по QUIC на указанном порту.

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

Список директив см. в ngx_http_v3_module.

Для включения проверки адреса:

quic_retry on;

Для включения 0-RTT:

ssl_early_data on;

Для включения GSO (Generic Segmentation Offloading):

quic_gso on;

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

quic_host_key <filename>;

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

По умолчанию, оптимизация GSO, специфичная для Linux, отключена. Включите её, если соответствующий сетевой интерфейс настроен для поддержки 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 {
        # for better compatibility it's recommended
        # to use the same port for quic and https
        listen 8443 quic reuseport;
        listen 8443 ssl;

        ssl_certificate     certs/example.com.crt;
        ssl_certificate_key certs/example.com.key;

        location / {
            # required for browsers to direct them to quic port
            add_header Alt-Svc 'h3=":8443"; ma=86400';
        }
    }
}

Отладка

Советы, которые могут помочь в идентификации проблем:

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