QUIC 및 HTTP/3 지원

QUIC 및 HTTP/3 프로토콜에 대한 지원은 1.25.0부터 가능합니다. 또한 1.25.0부터 Linux 바이너리 패키지에서 QUIC 및 HTTP/3 지원이 가능합니다.

QUIC 및 HTTP/3 지원은 실험적이므로 경고 사항이 적용됩니다.

소스에서 빌드(Building from sources)

빌드는 구성 명령을 사용하여 구성됩니다. 자세한 내용은 소스에서 nginx 빌드를 참조하세요.

nginx를 구성할 때 –with-http_v3_module 구성 매개변수를 사용하여 QUIC 및 HTTP/3를 활성화할 수 있습니다.

BoringSSL, LibreSSL 또는 QuicTLS와 같은 nginx를 빌드하려면 QUIC 지원을 제공하는 SSL 라이브러리를 사용하는 것이 좋습니다. 그렇지 않으면 초기 데이터를 지원하지 않는 OpenSSL 호환성 레이어가 사용됩니다.

BoringSSL로 nginx를 구성하려면 다음 명령을 사용하십시오.

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

또는 QuicTLS를 사용하여 nginx를 구성할 수 있습니다.

./configure
    --with-debug
    --with-http_v3_module
    --with-cc-opt="-I../quictls/build/include"
    --with-ld-opt="-L../quictls/build/lib"

또는 최신 버전의 LibreSSL을 사용하여 nginx를 구성할 수 있습니다.

./configure
    --with-debug
    --with-http_v3_module
    --with-cc-opt="-I../libressl/build/include"
    --with-ld-opt="-L../libressl/build/lib"

구성 후 make를 사용하여 nginx를 컴파일하고 설치합니다.

구성(Configuration)

ngx_http_core_module 모듈의 Listen 지시문에는 지정된 포트에서 QUIC를 통해 HTTP/3를 활성화하는 새로운 매개변수 quic이 있습니다.

quic 매개변수와 함께 재사용포트 매개변수를 지정하여 여러 워커에서 제대로 작동하도록 할 수도 있습니다.

지시어 목록은 ngx_http_v3_module을 참조하세요.

address validation을 활성화하려면:

quic_retry on;

0-RTT를 활성화하려면:

ssl_early_data on;

GSO(Generic Segmentation Offloading)를 활성화하려면:

quic_gso on;

다양한 토큰(token)에 대한 호스트 키(host key)를 설정하려면:

quic_host_key <filename>;

QUIC에는 ssl_protocols 지시어에서 기본적으로 활성화된 TLSv1.3 프로토콜 버전이 필요합니다.

기본적으로 GSO Linux 관련 최적화는 비활성화되어 있습니다. 해당 네트워크 인터페이스가 GSO를 지원하도록 구성된 경우 활성화합니다.

QUIC 구성 예시(Example Configuration) 

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';
        }
    }
}

Troubleshooting (QUIC)

문제를 식별하는 데 도움이 될 수 있는 팁:

  • 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"