H2O

the optimized HTTP/1.x, HTTP/2, HTTP/3 server

Powered by Oktavia

Configure > HTTP/3

HTTP/3 uses QUIC as the transport protocol. A listen directive with a type attribute set to quic instructs the standalone server to bind to a UDP port on which QUIC packets will be sent and received. The binding must have an ssl attribute, as QUIC uses TLS/1.3 as the handshake protocol.

The example below setups a server that listens to both TCP port 443 and UDP port 443 using the same certificate and private key.

First listen directive binds the server to TCP port 443 with specified credentials, marking that directive as an YAML alias called &listen_ssl. Then, it reuses (YAML merge) the first listen directive, adding type: quic to create a UDP port 443 binding for accepting QUIC connections.

Example. Serving HTTP/1,2 and 3 on port 443
listen: &listen_ssl
  port: 443
  ssl:
    certificate-file: /path/to-ssl-certificate-file
    key-file: /path/to/ssl-key-file
listen:
  <<: *listen_ssl
  type: quic

Fine-tuning QUIC Behavior

To fine tune the behavior of QUIC, the quic attribute should be used in place of the type attribute specifying quic. The quic attribute accepts following parameters.

amp-limit
Amount of data that can be sent to the client before the client address is validated; see section 8.1 of RFC 9000. Default is 3.
ecn
A boolean flag (either ON or OFF) indicating whether the server should use ECN signals to detect congestion. The default setting is ON. This flag affects the server's sending behavior. Regardless of this configuration, the server sends back ECN signals it receives using ACK_ECN frames.
handshake-timeout-rtt-multiplier
Handshake timeout in the unit of round-trip time. Default is 400.
jumpstart-default
Jumpstart enhances the slow start phase of congestion control by pacing a large number of packets for an entire round-trip time (RTT), allowing the server to assess the network's capacity sooner. This parameter specifies the number of packets sent during the jumpstart phase. The default value is zero, indicating that jumpstart is disabled for new connections.
jumpstart-max
Upon resuming QUIC connections, clients present tokens issued by the server that contain the bandwidth of the previous connection. This information enables the server to instantly match the previous send rate by adjusting the jumpstart window accordingly. This parameter sets a cap on the maximum size of the jumpstart window. If set to zero (the default), the server disregards the bandwidth values in the tokens. Nonetheless, the server may still initiate a jumpstart without using previous information, based on the jumpstart-default parameter.
max-initial-handshake-packets
Maximum number of Initial packets to be sent before the handshake is deemed to have failed. Default is 1,000.
max-streams-bidi
Maximum number of client-initated bi-directional streams. This parameter controls the HTTP request concurrency of a HTTP/3 connection. Default is 100.
max-udp-payload-size
See Section 18.2 of RFC 9000. Default is 1,472.
pacing
A boolean flag (either OFF or ON) indicating whether sent packets should be paced. The default setting is OFF.
qpack-encoder-table-capacity
Size of the QPACK encoder table. Default is 4,096.
respect-app-limited
This boolean flag (either OFF or ON) indicates whether the server should respect the notion of rate limited traffic when adjusting the size of the congestion window, as detailed in RFC 7661. The default setting is ON.
retry
A boolean flag (OFF or ON) indicating if a Retry packet should be used for validating the client address. Use of Retry packets mitigate denial-of-service attacks at the cost of incurring one additional round-trip for processing the handshake.
sndbuf, rcvbuf
Size of send and receive buffers, in the unit of bytes. Unlike the TCP counterparts that are per-connection, these buffers are associated to the listening port and applies to all the connections bound to that port.

The example below reuses a previous binding but sets the retry parameter to ON.

Example. HTTP/3 endpoint using Retry packets
listen:
  <<: *listen_ssl
  quic:
    retry: ON

Also, properties such as congestion controller and initial congestion window can be tuned using the top-level attribute of listen.

HTTP/3 Directives

Aside from QUIC-level properties, configuration directives listed below are provided for tuning HTTP/3 behavior.

Description:

Maximum duration to retain HTTP/3 connections in half-closed state, in seconds.

When a graceful shutdown of h2o is initiated, h2o at first sends a GOAWAY frame indicating the clients that it is initiating shutdown, then after one second, starts rejecting new HTTP requests (a.k.a. half-closed state).

This directive controls how long h2o should wait for the peer to close the QUIC connection in this half-closed state, before exitting.

If set to zero, this timeout is disabled. h2o will not shut down until all QUIC connections are closed by the clients or times out.

Level:
global
Default:
http3-graceful-shutdown-timeout: 0
Description:

If Generic Segmentation Offload should be used when sending QUIC packets.

Level:
global
Default:
http3-gso: ON
Description:

Idle timeout in the unit of seconds.

Unlike idle timeout of HTTP/1 and HTTP/2, this value should be small because it is faster to re-establish a new connection using 0-RTT than migrating to a different port due to NAT rebinding.

Level:
global
Default:
http3-idle-timeout: 30
Description:

Default window size for HTTP request body.

See http2-input-window-size.

Level:
global
Default:
http3-input-window-size: 16777216
Description:

Maximum number of streaming requests to be handled concurrently within a single HTTP/3 connection.

Level:
global
Default:
http3-max-concurrent-streaming-requests-per-connection: 1