msquic/docs/Settings.md

MsQuic Settings

MsQuic supports a number of configuration knobs (or settings). These settings can either be set dynamically (via the QUIC_SETTINGS structure) or via persistent storage (e.g. registry on Windows).

Warning Generally MsQuic already choses the best / most correct default values for all settings. Settings should only be changed after due diligence and A/B testing is performed.

MsQuic settings are available on most MsQuic API objects. Here we'll provide an overview of them with links to further details.

Windows Registry

MsQuic supports most of the settings in the QUIC_SETTINGS struct in the registry to be loaded as defaults when the MsQuic library is loaded in a process. These registry settings only provide the defaults; the application is free to change the settings with a call to SetParam or in QUIC_SETTINGS structs passed into ConfigurationOpen.

The default settings are updated automatically in the application when changing the registry, assuming the application hasn't already changed the setting, which overrides the registry value. However, this does not change the settings on Connections which are already established, or Configurations which are already created.

Note: MaxWorkerQueueDelay uses milliseconds in the registry, but uses microseconds (us) in the QUIC_SETTINGS struct.

The following settings are unique to the registry:

Setting	Type	Registry Name	Default	Description
Max Worker Queue Delay	uint32_t	MaxWorkerQueueDelayMs	250	The maximum queue delay (in ms) allowed for a worker thread.
Max Partition Count	uint16_t	MaxPartitionCount	System CPU count	The maximum processor count used for partitioning work in MsQuic. Max 512. Restart is required.

The following settings are available via registry as well as via QUIC_SETTINGS:

Setting	Type	Registry Name	Default	Description
Max Bytes per Key	uint64_t	MaxBytesPerKey	274,877,906,944	Maximum number of bytes to encrypt with a single 1-RTT encryption key before initiating key update.
Handshake Idle Timeout	uint64_t	HandshakeIdleTimeoutMs	10,000	How long a handshake can idle before it is discarded.
Idle Timeout	uint64_t	IdleTimeoutMs	30,000	How long a connection can go idle before it is silently shut down. 0 to disable timeout
Max TLS Send Buffer (Client)	uint32_t	TlsClientMaxSendBuffer	4,096	How much client TLS data to buffer.
Max TLS Send Buffer (Server)	uint32_t	TlsServerMaxSendBuffer	8,192	How much server TLS data to buffer.
Stream Receive Window	uint32_t	StreamRecvWindowDefault	65,536	Initial stream receive window size for all stream types.
Stream Receive Window (Bidirectional, locally created)	uint32_t	StreamRecvWindowBidiLocalDefault	-	If set, overrides stream receive window size for locally initiated bidirectional streams.
Stream Receive Window (Bidirectional, remotely created)	uint32_t	StreamRecvWindowBidiRemoteDefault	-	If set, overrides stream receive window size for remote initiated bidirectional streams.
Stream Receive Window (Unidirectional)	uint32_t	StreamRecvWindowUnidiDefault	-	If set, overrides stream receive window size for remote initiated unidirectional streams.
Stream Receive Buffer	uint32_t	StreamRecvBufferDefault	4,096	Stream initial buffer size.
Flow Control Window	uint32_t	ConnFlowControlWindow	16,777,216	Connection-wide flow control window.
Max Stateless Operations	uint32_t	MaxStatelessOperations	16	The maximum number of stateless operations that may be queued on a worker at any one time.
Initial Window	uint32_t	InitialWindowPackets	10	The size (in packets) of the initial congestion window for a connection.
Send Idle Timeout	uint32_t	SendIdleTimeoutMs	1,000	Reset congestion control after being idle SendIdleTimeoutMs milliseconds.
Initial RTT	uint32_t	InitialRttMs	333	Initial RTT estimate.
Max ACK Delay	uint32_t	MaxAckDelayMs	25	How long to wait after receiving data before sending an ACK.
Disconnect Timeout	uint32_t	DisconnectTimeoutMs	16,000	How long to wait for an ACK before declaring a path dead and disconnecting.
Keep Alive Interval	uint32_t	KeepAliveIntervalMs	0 (disabled)	How often to send PING frames to keep a connection alive.
Idle Timeout Period Changes DestCid	uint32_t	DestCidUpdateIdleTimeoutMs	20,000	Idle timeout period after which the destination CID is updated before sending again.
Peer Stream Count (Bidirectional)	uint16_t	PeerBidiStreamCount	0	Number of bidirectional streams to allow the peer to open.
Peer Stream Count (Unidirectional)	uint16_t	PeerUnidiStreamCount	0	Number of unidirectional streams to allow the peer to open.
Retry Memory Limit	uint16_t	RetryMemoryFraction	65 (~0.1%)	The percentage of available memory usable for handshake connections before stateless retry is used. Calculated as N/65535.
Load Balancing Mode	uint16_t	LoadBalancingMode	0 (disabled)	Global setting, not per-connection/configuration.
Max Operations per Drain	uint8_t	MaxOperationsPerDrain	16	The maximum number of operations to drain per connection quantum.
Send Buffering	uint8_t	SendBufferingEnabled	1 (TRUE)	Buffer send data within MsQuic instead of holding application buffers until sent data is acknowledged.
Send Pacing	uint8_t	PacingEnabled	1 (TRUE)	Pace sending to avoid overfilling buffers on the path.
Client Migration Support	uint8_t	MigrationEnabled	1 (TRUE)	Enable clients to migrate IP addresses and tuples. Requires a cooperative load-balancer, or no load-balancer.
Datagram Receive Support	uint8_t	DatagramReceiveEnabled	0 (FALSE)	Advertise support for QUIC datagram extension.
Server Resumption Level	uint8_t	ServerResumptionLevel	0 (No resumption)	Server only. Controls resumption tickets and/or 0-RTT server support.
Grease Quic Bit Support	uint8_t	GreaseQuicBitEnabled	0 (FALSE)	Advertise support for Grease QUIC Bit extension.
Minimum MTU	uint16_t	MinimumMtu	1288	The minimum MTU supported by a connection. This will be used as the starting MTU.
Maximum MTU	uint16_t	MaximumMtu	1500	The maximum MTU supported by a connection. This will be the maximum probed value.
MTU Discovery Search Timeout	uint64_t	MtuDiscoverySearchCompleteTimeoutUs	600000000	The time in microseconds to wait before reattempting MTU probing if max was not reached.
MTU Discovery Missing Probe Count	uint8_t	MtuDiscoveryMissingProbeCount	3	The number of MTU probes to retry before exiting MTU probing.
Max Binding Stateless Operations	uint16_t	MaxBindingStatelessOperations	100	The maximum number of stateless operations that may be queued on a binding at any one time.
Stateless Operation Expiration	uint16_t	StatelessOperationExpirationMs	100	The time limit between operations for the same endpoint, in milliseconds.
Congestion Control Algorithm	uint16_t	CongestionControlAlgorithm	0 (Cubic)	The congestion control algorithm used for the connection.
ECN	uint8_t	EcnEnabled	0 (FALSE)	Enable sender-side ECN support.

The types map to registry types as follows:

• uint64_t is a REG_QWORD.
• uint32_t, uint16_t, and uint8_t are REG_DWORD.

While REG_DWORD can hold values larger than uint16_t, the administrator should ensure they do not exceed the maximum value of 65,535 when configuring a uint16_t setting via the Windows Registry.

The following settings are available via registry as well as via QUIC_VERSION_SETTINGS:

Setting	Type	Registry Name	Default	Description
Acceptable Versions List	uint32_t[]	AcceptableVersions	Unset	Sets the list of versions that a given server instance will use if a client sends a first flight using them.
Offered Versions List	uint32_t[]	OfferedVersions	Unset	Sets the list of versions that a given server instance will send in a Version Negotiation packet if it receives a first flight from an unknown version. This list will most often be equal to the Acceptable Versions list.
Fully-Deployed Versions List	uint32_t[]	FullyDeployedVersions	Unset	Sets the list of QUIC versions that is supported and negotiated by every single QUIC server instance in this deployment. Used to generate the AvailableVersions list in the Version Negotiation Extension Transport Parameter.

The uint32_t[] type is a REG_BINARY blob of the versions list, with each version in little-endian format.

All restrictions and effects on the versions mentioned in QUIC_VERSION_SETTINGS apply to the registry-set versions as well.

Particularly, on server, these must be set GLOBALLY if you want them to take effect for servers.

QUIC_SETTINGS

A QUIC_SETTINGS struct is used to configure settings on a Configuration handle, Connection handle, or globally.

For more details see QUIC_SETTINGS.

API Object Parameters

MsQuic API Objects have a number of settings, or parameters, which can be queried via GetParam, or can be set/modifed via SetParam.

Global Parameters

These parameters are accessed by calling GetParam or SetParam with QUIC_PARAM_GLOBAL_* and a NULL object handle.

Setting	Type	Get/Set	Description
QUIC_PARAM_GLOBAL_RETRY_MEMORY_PERCENT 0	uint16_t	Both	The percentage of available memory usable for handshake connections before stateless retry is used.
QUIC_PARAM_GLOBAL_SUPPORTED_VERSIONS 1	uint32_t[]	Get-only	List of QUIC protocol versions supported in network byte order.
QUIC_PARAM_GLOBAL_LOAD_BALACING_MODE 2	uint16_t	Both	Must be a QUIC_LOAD_BALANCING_MODE.
QUIC_PARAM_GLOBAL_PERF_COUNTERS 3	uint64_t[]	Get-only	Array size is QUIC_PERF_COUNTER_MAX.
QUIC_PARAM_GLOBAL_LIBRARY_VERSION 4	uint32_t[4]	Get-only	MsQuic API version.
QUIC_PARAM_GLOBAL_SETTINGS 5	QUIC_SETTINGS	Both	Globally change settings for all subsequent connections.
QUIC_PARAM_GLOBAL_GLOBAL_SETTINGS 6	QUIC_GLOBAL_SETTINGS	Both	Globally change global only settings.
QUIC_PARAM_GLOBAL_VERSION_SETTINGS 7	QUIC_VERSIONS_SETTINGS	Both	Globally change version settings for all subsequent connections.
QUIC_PARAM_GLOBAL_LIBRARY_GIT_HASH 8	char[64]	Get-only	Git hash used to build MsQuic (null terminated string)
QUIC_PARAM_GLOBAL_EXECUTION_CONFIG 9	QUIC_EXECUTION_CONFIG	Both	Globally configure the execution model used for QUIC. Must be set before opening registration.
QUIC_PARAM_GLOBAL_TLS_PROVIDER 10	QUIC_TLS_PROVIDER	Get-Only	The TLS provider being used by MsQuic for the TLS handshake.
QUIC_PARAM_GLOBAL_STATELESS_RESET_KEY 11	uint8_t[]	Set-Only	Globally change the stateless reset key for all subsequent connections.

Registration Parameters

These parameters are accessed by calling GetParam or SetParam with QUIC_PARAM_REGISTRATION_* and a Registration object handle.

Setting	Type	Get/Set	Description

Configuration Parameters

These parameters are accessed by calling GetParam or SetParam with QUIC_PARAM_CONFIGURATION_* and a Configuration object handle.

Setting	Type	Get/Set	Description
QUIC_PARAM_CONFIGURATION_SETTINGS 0	QUIC_SETTINGS	Both	Settings to use for all connections sharing this Configuration. See QUIC_SETTINGS.
QUIC_PARAM_CONFIGURATION_TICKET_KEYS 1	QUIC_TICKET_KEY_CONFIG[]	Set-only	Resumption ticket encryption keys. Server-side only.
QUIC_PARAM_CONFIGURATION_VERSION_SETTINGS 2	QUIC_VERSIONS_SETTINGS	Both	Change version settings for all connections on the configuration.
QUIC_PARAM_CONFIGURATION_SCHANNEL_CREDENTIAL_ATTRIBUTE_W 3	QUIC_SCHANNEL_CREDENTIAL_ATTRIBUTE_W	Set-only	Calls SetCredentialsAttributesW with the supplied attribute and buffer on the credential handle. Schannel-only. Only valid once the credential has been loaded.

Listener Parameters

These parameters are accessed by calling GetParam or SetParam with QUIC_PARAM_LISTENER_* and a Listener object handle.

Setting	Type	Get/Set	Description
QUIC_PARAM_LISTENER_LOCAL_ADDRESS 0	QUIC_ADDR	Get-only	Get the full address tuple the server is listening on.
QUIC_PARAM_LISTENER_STATS 1	QUIC_LISTENER_STATISTICS	Get-only	Get statistics specific to this Listener instance.
QUIC_PARAM_LISTENER_CIBIR_ID 2	uint8_t[]	Both	The CIBIR well-known idenfitier.

Connection Parameters

These parameters are accessed by calling GetParam or SetParam with QUIC_PARAM_CONNECTION_* and a Connection object handle.

Setting	Type	Get/Set	Description
QUIC_PARAM_CONN_QUIC_VERSION 0	uint32_t	Get-only	Negotiated QUIC protocol version
QUIC_PARAM_CONN_LOCAL_ADDRESS 1	QUIC_ADDR	Both	Set on client only. Must be set before start or after handshake confirmed.
QUIC_PARAM_CONN_REMOTE_ADDRESS 2	QUIC_ADDR	Both	Set on client only. Must be set before start.
QUIC_PARAM_CONN_IDEAL_PROCESSOR 3	uint16_t	Get-only	Ideal processor for the app to send from.
QUIC_PARAM_CONN_SETTINGS 4	QUIC_SETTINGS	Both	Connection settings. See QUIC_SETTINGS
QUIC_PARAM_CONN_STATISTICS 5	QUIC_STATISTICS	Get-only	Connection-level statistics.
QUIC_PARAM_CONN_STATISTICS_PLAT 6	QUIC_STATISTICS	Get-only	Connection-level statistics with platform-specific time format.
QUIC_PARAM_CONN_SHARE_UDP_BINDING 7	uint8_t (BOOLEAN)	Both	Set on client only. Must be called before start.
QUIC_PARAM_CONN_LOCAL_BIDI_STREAM_COUNT 8	uint16_t	Get-only	Number of bidirectional streams available.
QUIC_PARAM_CONN_LOCAL_UNIDI_STREAM_COUNT 9	uint16_t	Get-only	Number of unidirectional streams available.
QUIC_PARAM_CONN_MAX_STREAM_IDS 10	uint64_t[4]	Get-only	Array of number of client and server, bidirectional and unidirectional streams.
QUIC_PARAM_CONN_CLOSE_REASON_PHRASE 11	char[]	Both	Max length 512 chars.
QUIC_PARAM_CONN_STREAM_SCHEDULING_SCHEME 12	QUIC_STREAM_SCHEDULING_SCHEME	Both	Whether to use FIFO or round-robin stream scheduling.
QUIC_PARAM_CONN_DATAGRAM_RECEIVE_ENABLED 13	uint8_t (BOOLEAN)	Both	Indicate/query support for QUIC datagram extension. Must be set before start.
QUIC_PARAM_CONN_DATAGRAM_SEND_ENABLED 14	uint8_t (BOOLEAN)	Get-only	Indicates peer advertised support for QUIC datagram extension. Call after connected.
QUIC_PARAM_CONN_DISABLE_1RTT_ENCRYPTION 15	uint8_t (BOOLEAN)	Both	Application must #define QUIC_API_ENABLE_INSECURE_FEATURES before including msquic.h.
QUIC_PARAM_CONN_RESUMPTION_TICKET 16	uint8_t[]	Set-only	Must be set on client before starting connection.
QUIC_PARAM_CONN_PEER_CERTIFICATE_VALID 17	uint8_t (BOOLEAN)	Set-only	Used for asynchronous custom certificate validation. Deprecated soon. Replaced by ConnectionCertificateValidationComplete
QUIC_PARAM_CONN_LOCAL_INTERFACE 18	uint32_t	Set-only	The local interface index to bind to.
QUIC_PARAM_CONN_TLS_SECRETS 19	QUIC_TLS_SECRETS	Set-only	The TLS secrets struct to be populated by MsQuic.
QUIC_PARAM_CONN_VERSION_SETTINGS 20	QUIC_VERSION_SETTINGS	Both	The desired QUIC versions for the connection.
QUIC_PARAM_CONN_CIBIR_ID 21	uint8_t[]	Set-only	The CIBIR well-known identifier.
QUIC_PARAM_CONN_STATISTICS_V2 22	QUIC_STATISTICS_V2	Get-only	Connection-level statistics, version 2.
QUIC_PARAM_CONN_STATISTICS_V2_PLAT 23	QUIC_STATISTICS_V2	Get-only	Connection-level statistics with platform-specific time format, version 2.
QUIC_PARAM_CONN_ORIG_DEST_CID 24	uint8_t[]	Get-only	The original destination connection ID used by the client to connect to the server.

QUIC_PARAM_CONN_STATISTICS_V2

Querying the QUIC_STATISTICS_V2 struct via QUIC_PARAM_CONN_STATISTICS_V2 or QUIC_PARAM_CONN_STATISTICS_V2_PLAT should be aware of possible changes in the size of the struct, depending on the version of MsQuic the app using at runtime, not just what it was compiled against.

The minimum size of the struct will always be QUIC_STATISTICS_V2_SIZE_1. Future version of MsQuic will append new fields to the end of the struct, so the maximum possible size will increase.

When an app queries for the statistics, it must always supply an input buffer of length at least QUIC_STATISTICS_V2_SIZE_1, but sizeof(QUIC_STATISTICS_V2) will always work as well. MsQuic will support older callers that supply at least that buffer size, even if the maximum size of the struct has grown in a future version of MsQuic. MsQuic will only write the fields that can completely fit in the buffer supplied by the app.

TLS Parameters

These parameters are accessed by calling GetParam or SetParam with QUIC_PARAM_TLS_* and a Connection object handle.

Setting	Type	Get/Set	Description
QUIC_PARAM_TLS_HANDSHAKE_INFO 0	QUIC_HANDSHAKE_INFO	Get-only	Called in the QUIC_CONNECTION_EVENT_CONNECTED event to get the cryptographic parameters negotiated in the handshake.
QUIC_PARAM_TLS_NEGOTIATED_ALPN 1	uint8_t[] (max 255 bytes)	Get-only	Called in the QUIC_CONNECTION_EVENT_CONNECTED event to get the negotiated ALPN.

Schannel-only TLS Parameters

These parameters are access by calling GetParam or SetParam with QUIC_PARAM_TLS_SCHANNEL_* and a Connection object handle.

Setting	Type	Get/Set	Description
QUIC_PARAM_TLS_SCHANNEL_CONTEXT_ATTRIBUTE_W 0	QUIC_SCHANNEL_CONTEXT_ATTRIBUTE_W	Get-only	Calls QueryContextAttributesW for the given attribute and buffer. Only valid until the QUIC_CONNECTION_EVENT_CONNECTED event, or when TLS is cleaned up.
QUIC_PARAM_TLS_SCHANNEL_CONTEXT_ATTRIBUTE_EX_W 1	QUIC_SCHANNEL_CONTEXT_ATTRIBUTE_EX_W	Get-only	Calls QueryContextAttributesExW for the given attribute and buffer. Only valid until the QUIC_CONNECTION_EVENT_CONNECTED event, or when TLS is cleaned up.
QUIC_PARAM_TLS_SCHANNEL_SECURITY_CONTEXT_TOKEN 2	HANDLE	Get-only	Calls QuerySecurityContextToken on the Schannel handle. Only valid until the QUIC_CONNECTION_EVENT_CONNECTED event, or when TLS is cleaned up.

Stream Parameters

These parameters are access by calling GetParam or SetParam with QUIC_PARAM_STREAM_* and a Stream object handle.

Setting	Type	Get/Set	Description
QUIC_PARAM_STREAM_ID 0	QUIC_UINT62	Get-only	Must be called on a stream after StreamStart is called.
QUIC_PARAM_STREAM_0RTT_LENGTH 1	uint64_t	Get-only	Length of 0-RTT data received from peer.
QUIC_PARAM_STREAM_IDEAL_SEND_BUFFER_SIZE 2	uint64_t - bytes	Get-only	Ideal buffer size to queue to the stream. Assumes only one stream sends steadily.
QUIC_PARAM_STREAM_PRIORITY 3	uint16_t	Get/Set	Stream priority.
QUIC_PARAM_STREAM_STATISTICS 4	QUIC_STREAM_STATISTICS	Get-only	Stream-level statistics.
QUIC_PARAM_STREAM_RELIABLE_OFFSET 5	uint64_t	Get/Set	Part of the new Reliable Reset preview feature. Sets/Gets the number of bytes a sender must send before closing SEND path.

See Also

QUIC_SETTINGS
GetParam
SetParam