Модуль http_v3

Обеспечивает поддержку протокола HTTP/3 для соединений с клиентами, а также для соединений с проксируемыми серверами, настраиваемых при помощи следующих директив из модуля http_proxy:

• proxy_http3_hq

• proxy_http3_max_concurrent_streams

• proxy_http3_stream_buffer_size

• proxy_http_version

• proxy_pass

• proxy_quic_active_connection_id_limit

• proxy_quic_gso

• proxy_quic_host_key

По умолчанию этот модуль не собирается; его необходимо включить с помощью параметра конфигурации сборки ‑‑with‑http_v3_module. В пакетах из наших репозиториев модуль включен в сборку.

Для сборки настоятельно рекомендуется использовать библиотеку SSL, поддерживающую протокол QUIC:

BoringSSLQuicTLS

Сборка с 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"

Без этого будет использована библиотека OpenSSL в режиме совместимости, где не поддерживается ранняя отправка данных (early data) и нет других функций, например повторного использования сессий. Такая сборка сможет взаимодействовать только с клиентами и серверами, использующими OpenSSL в том же режиме.

Пример конфигурации

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 {
        # для лучшей совместимости рекомендуется
        # использовать одинаковый порт для http/3 и https
        listen 8443 quic reuseport;
        listen 8443 ssl;

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

        location / {
            # используется для объявления о поддержке http/3
            add_header Alt-Svc 'h3=":8443"; ma=86400';
        }
    }
}

Важно

Чтобы принимать HTTP/3-соединения по TLS, необходимо наличие поддержки протокола TLSv1.3, появившейся в OpenSSL версии 1.1.1.

Директивы

http3

Синтаксис:

http3 on | off;

Умолчание:

http3 on;

Контекст:

http, server

Разрешает согласование протокола HTTP/3.

http3_hq

Синтаксис:

http3_hq on | off;

Умолчание:

http3_hq off;

Контекст:

http, server

Разрешает согласование протокола HTTP/0.9, используемого в функциональных тестах QUIC.

http3_max_concurrent_streams

Синтаксис:

http3_max_concurrent_streams число;

Умолчание:

http3_max_concurrent_streams 128;

Контекст:

http, server

Задает максимальное число параллельных HTTP/3-потоков в соединении.

http3_stream_buffer_size

Синтаксис:

http3_stream_buffer_size размер;

Умолчание:

http3_stream_buffer_size 64k;

Контекст:

http, server

Задает размер буфера, используемого для чтения и записи QUIC-потоков.

quic_active_connection_id_limit

Синтаксис:

quic_active_connection_id_limit число;

Умолчание:

quic_active_connection_id_limit 2;

Контекст:

http, server

Устанавливает значение транспортного параметра QUIC active_connection_id_limit. Это максимальное значение ID соединений, возможное для хранения на сервере.

quic_bpf

Синтаксис:

quic_bpf on | off;

Умолчание:

quic_bpf off;

Контекст:

main

Разрешает маршрутизацию пакетов QUIC при помощи eBPF. Если маршрутизация включена, то обеспечивается поддержка миграции QUIC-соединений.

Важно

Директива поддерживается только на Linux 5.7+.

quic_gso

Синтаксис:

quic_gso on | off;

Умолчание:

quic_gso off;

Контекст:

http, server

Разрешает отправку оптимизированного пакетного режима при помощи segmentation offloading.

Важно

Оптимизированная отправка поддерживается только на Linux с поддержкой UDP_SEGMENT.

quic_host_key

Синтаксис:

quic_host_key файл;

Умолчание:

—

Контекст:

http, server

Задает файл с секретным ключом, применяемым при шифровании stateless reset и address validation токенов. По умолчанию создается случайный ключ при каждой перезагрузке. Токены, созданные при помощи старых ключей, не принимаются.

quic_retry

Синтаксис:

quic_retry on | off;

Умолчание:

quic_retry off;

Контекст:

http, server

Разрешает функциональность QUIC Address Validation, в том числе отправку нового токена в Retry-пакете или NEW_TOKEN frame и валидацию токена, полученного в Initial-пакете.

Встроенные переменные

Модуль http_v3 поддерживает следующие встроенные переменные:

$http3

согласованный идентификатор протокола:

h3	для HTTP/3-соединений
hq	для hq-соединений
""	пустая строка для остальных случаев

$quic_connection

порядковый номер QUIC-соединения