ASP.NET Core Kestrel 웹 서버의 옵션 구성

Kestrel 웹 서버에는 인터넷 연결 배포에 특히 유용한 제약 조건 구성 옵션이 있습니다. Kestrel 구성 옵션을 구성하려면 Program.cs에서 ConfigureKestrel을 호출합니다.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    // ...
});

KestrelServerOptions.Limits 속성에서 제약 조건을 설정합니다. 이 속성은 KestrelServerLimits 클래스의 인스턴스를 보유합니다.

일반 제한

Keep-alive 시간 제한

KeepAliveTimeout은 keep-alive 시간 제한을 가져오거나 설정합니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
});

이 시간 제한은 디버거가 프로세스에 Kestrel 연결된 경우 적용되지 않습니다.

최대 클라이언트 연결

MaxConcurrentConnections는 최대 열린 연결 수를 가져오거나 설정합니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
});

MaxConcurrentUpgradedConnections는 최대 열린, 업그레이드된 연결 수를 가져오거나 설정합니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
});

업그레이드된 연결은 HTTP에서 WebSocket과 같은 다른 프로토콜로 전환된 연결입니다. 연결이 업그레이드된 후 MaxConcurrentConnections 제한에 대해 계산되지 않습니다.

최대 요청 본문 크기

MaxRequestBodySize는 요청 본문에 대해 허용되는 최대 크기(바이트)를 가져오거나 설정합니다.

ASP.NET Core MVC 앱에서 한도를 재정의할 때는 작업 메서드에서 RequestSizeLimitAttribute 특성을 사용하는 방법이 좋습니다.

[RequestSizeLimit(100_000_000)]
public IActionResult Get()

다음 예제에서는 모든 요청에 대해 MaxRequestBodySize를 구성합니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxRequestBodySize = 100_000_000;
});

다음 예제에서는 사용자 지정 미들웨어에서 IHttpMaxRequestBodySizeFeature를 사용하여 특정 요청에 대한 MaxRequestBodySize를 구성합니다.

app.Use(async (context, next) =>
{
    var httpMaxRequestBodySizeFeature = context.Features.Get<IHttpMaxRequestBodySizeFeature>();

    if (httpMaxRequestBodySizeFeature is not null)
        httpMaxRequestBodySizeFeature.MaxRequestBodySize = 10 * 1024;

    // ...

    await next(context);
});

요청을 읽기 시작한 후 앱에서 요청에 대한 제한을 구성하려고 하면 예외가 throw됩니다. IHttpMaxRequestBodySizeFeature.IsReadOnly 속성을 사용하여 MaxRequestBodySize 속성을 설정해도 안전한지 확인합니다.

앱이 ASP.NET Core 모듈 뒤에서 Out of Process로 실행되는 경우 IIS는 제한을 설정하고 Kestrel의 요청 본문 크기 제한이 사용되지 않습니다.

최소 요청 본문 데이터 속도

Kestrel은 데이터가 지정된 속도(바이트/초)로 도착하는지 1초마다 확인합니다. 속도가 최소 아래로 떨어지면 연결이 시간 초과됩니다. 유예 기간은 Kestrel에서 클라이언트가 전송 속도를 최소로 높일 수 있는 시간입니다. 이 기간에는 속도가 확인되지 않습니다. 유예 기간은 TCP 느린 시작으로 인해 느린 속도로 처음에 데이터를 보내는 연결 중단을 방지하는 데 도움이 됩니다. 최소 속도는 응답에도 적용됩니다.

MinRequestBodyDataRate는 요청 본문 최소 데이터 속도(바이트/초)를 가져오거나 설정합니다. MinResponseDataRate는 응답 본문 최소 데이터 속도(바이트/초)를 가져오거나 설정합니다.

다음 예제에서는 모든 요청에 대해 MinRequestBodyDataRate 및 MinResponseDataRate를 구성합니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MinRequestBodyDataRate = new MinDataRate(
        bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate = new MinDataRate(
        bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
});

다음 예제에서는 사용자 지정 미들웨어에서 IHttpMinRequestBodyDataRateFeature 및 IHttpMinResponseDataRateFeature를 사용하여 특정 요청에 대한 MinRequestBodyDataRate 및 MinResponseDataRate를 구성합니다.

app.Use(async (context, next) =>
{
    var httpMinRequestBodyDataRateFeature = context.Features
        .Get<IHttpMinRequestBodyDataRateFeature>();

    if (httpMinRequestBodyDataRateFeature is not null)
    {
        httpMinRequestBodyDataRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

    var httpMinResponseDataRateFeature = context.Features
        .Get<IHttpMinResponseDataRateFeature>();

    if (httpMinResponseDataRateFeature is not null)
    {
        httpMinResponseDataRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

    // ...

    await next(context);
});

IHttpMinResponseDataRateFeature는 HTTP/2 요청에 대한 HttpContext.Features에 없습니다. 프로토콜의 요청 멀티플렉싱 지원 때문에 HTTP/2의 경우 일반적으로 각 요청을 기준으로 속도 제한을 수정할 수 없습니다. 그러나 HTTP/2 요청에 대해서도 IHttpMinResponseDataRateFeature.MinDataRate를 null로 설정하여 요청별 읽기 속도 제한을 완전히 비활성화할 수 있으므로 HTTP/2 요청에 대한 IHttpMinRequestBodyDataRateFeature는 여전히 존재합니다HttpContext.Features. IHttpMinRequestBodyDataRateFeature.MinDataRate를 읽으려는 시도나 null 이외의 값으로 설정하려는 시도로 인해 HTTP/2 요청에 대한 NotSupportedException이 발생합니다.

KestrelServerOptions.Limits를 통해 구성된 서버 전체 속도 제한은 여전히 HTTP/1.x 및 HTTP/2 연결 모두에 적용됩니다.

요청 헤더 시간 제한

RequestHeadersTimeout은 서버가 요청 헤더를 수신하는 데 걸리는 최대 시간을 가져오거나 설정합니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

이 시간 제한은 디버거가 프로세스에 Kestrel 연결된 경우 적용되지 않습니다.

HTTP/2 제한

이 섹션의 제한은 KestrelServerLimits.Http2에 설정되어 있습니다.

연결당 최대 스트림

MaxStreamsPerConnection은 HTTP/2 연결당 동시 요청 스트림 수를 제한합니다. 초과 스트림은 거부됩니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxStreamsPerConnection = 100;
});

헤더 테이블 크기

HeaderTableSize는 서버의 HPACK 인코더 및 디코더에서 사용할 수 있는 헤더 압축 테이블의 크기(8진수)를 제한합니다. HPACK 디코더는 HTTP/2 연결에 대한 HTTP 헤더의 압축을 풉니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.HeaderTableSize = 4096;
});

최대 프레임 크기

MaxFrameSize는 수신이 허용된 가장 큰 프레임 페이로드의 크기(8진수)를 나타냅니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxFrameSize = 16_384;
});

최대 요청 헤더 크기

MaxRequestHeaderFieldSize는 요청 헤더 필드 시퀀스의 허용되는 최대 크기를 나타냅니다. 이 한도는 모두 압축된 표현과 압축되지 않은 표현으로 이름과 값 시퀀스 모두에 적용됩니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.MaxRequestHeaderFieldSize = 8192;
});

초기 연결 창 크기

InitialConnectionWindowSize는 서버가 수신하려는 요청 본문 데이터와 연결당 모든 요청(스트림)에 걸쳐 한 번에 집계된 버퍼의 크기를 나타냅니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.InitialConnectionWindowSize = 131_072;
});

요청은 InitialStreamWindowSize에 의해서도 제한됩니다.

초기 스트림 창 크기

InitialStreamWindowSize는 서버가 수신하려는 요청 본문 데이터와 연결당 스트림당 버퍼의 크기를 나타냅니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.InitialStreamWindowSize = 98_304;
});

요청은 InitialConnectionWindowSize에 의해서도 제한됩니다.

HTTP/2 연결 유지 ping 구성

연결된 클라이언트로 HTTP/2 ping을 보내도록 Kestrel을 구성할 수 있습니다. HTTP/2 ping은 여러 가지 용도로 사용됩니다.

• 유휴 연결을 활성 상태로 유지합니다. 일부 클라이언트 및 프록시 서버는 유휴 상태인 연결을 닫습니다. HTTP/2 ping은 연결에 대한 작업으로 간주하며 연결이 유휴 상태로 닫히지 않도록 합니다.
• 비정상 연결을 닫습니다. 클라이언트가 구성된 시간에 연결 유지 ping에 응답하지 않는 연결은 서버에서 닫습니다.

HTTP/2 연결 유지 ping과 관련된 두 가지 구성 옵션이 있습니다.

• KeepAlivePingDelay은 ping 간격을 구성하는 TimeSpan입니다. 서버가 이 기간 동안 프레임을 받지 못하면 클라이언트로 연결 유지 ping을 보냅니다. 이 옵션을 TimeSpan.MaxValue로 설정하면 연결 유지 ping을 사용할 수 없습니다.
• KeepAlivePingTimeout은 ping 시간 제한을 구성하는 TimeSpan입니다. 서버가 이 시간 제한 동안 응답 ping과 같은 프레임을 받지 못하면 연결이 닫힙니다. 이 옵션을 TimeSpan.MaxValue로 설정하면 연결 유지 시간 제한을 사용할 수 없습니다.

다음 예제에서는 KeepAlivePingDelay를 KeepAlivePingTimeout으로 설정합니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.Http2.KeepAlivePingDelay = TimeSpan.FromSeconds(30);
    serverOptions.Limits.Http2.KeepAlivePingTimeout = TimeSpan.FromMinutes(1);
});

기타 옵션

동기 I/O

AllowSynchronousIO는 요청 및 응답에 대해 동기 I/O가 허용되는지 여부를 제어합니다.

Warning

차단 동기 I/O 작업 수가 많으면 스레드 풀이 고갈되어 앱이 응답하지 않게 될 수 있습니다. 비동기 I/O를 지원하지 않는 라이브러리를 사용할 때만 AllowSynchronousIO를 사용하도록 설정하세요.

다음 예제에서는 동기 I/O를 사용하도록 설정합니다.

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.AllowSynchronousIO = true;
});

다른 Kestrel 옵션 및 제한에 대한 정보는 다음을 참조하세요.

• KestrelServerOptions
• KestrelServerLimits
• ListenOptions

디버거가 연결된 동작

특정 시간 제한 및 속도 제한은 디버거가 프로세스에 Kestrel 연결된 경우 적용되지 않습니다. 자세한 내용은 디버거가 연결된 동작을 참조하세요.