Skip to content

Commit

Permalink
Improve version deployment documentation (#4646)
Browse files Browse the repository at this point in the history
  • Loading branch information
@anrossi
anrossi authored Nov 6, 2024
1 parent 709d700 commit 9587f74
Show file tree
Hide file tree
Showing 3 changed files with 38 additions and 9 deletions.
5 changes: 5 additions & 0 deletions docs/Deployment.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,11 @@ MsQuic uses worker threads internally to execute the QUIC protocol logic. For ea

The queue delay threshold can be configured via the `MaxWorkerQueueDelayMs` setting.

## Version Negotiation

MsQuic supports QUIC protocol versions 1 and 2, and the version negotiation extension. By default, version negotiation is off, but can be enabled at runtime.
Instructions for configuring and deploying QUIC versions are at [Versions](Versions.md).

# Diagnostics

For details on how to diagnose any issues with your deployment at the MsQuic layer see [Diagnostics](Diagnostics.md).
13 changes: 8 additions & 5 deletions docs/Settings.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,11 +74,12 @@ While `REG_DWORD` can hold values larger than `uint16_t`, the administrator shou

The following settings are available via registry as well as via [QUIC_VERSION_SETTINGS](./Versions.md):

| 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. |
| 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. |
| Version Negotiation Ext. Enabled | uint32_t | VersionNegotiationExtEnabled | 0 (FALSE) | Enables the Version Negotiation Extension. |

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

Expand Down Expand Up @@ -114,6 +115,7 @@ These parameters are accessed by calling [GetParam](./api/GetParam.md) or [SetPa
| `QUIC_PARAM_GLOBAL_EXECUTION_CONFIG`<br> 9 | QUIC_EXECUTION_CONFIG | Both | Globally configure the execution model used for QUIC. Must be set before opening registration. |
| `QUIC_PARAM_GLOBAL_TLS_PROVIDER`<br> 10 | QUIC_TLS_PROVIDER | Get-Only | The TLS provider being used by MsQuic for the TLS handshake. |
| `QUIC_PARAM_GLOBAL_STATELESS_RESET_KEY`<br> 11 | uint8_t[] | Set-Only | Globally change the stateless reset key for all subsequent connections. |
| `QUIC_PARAM_GLOBAL_VERSION_NEGOTIATION_ENABLED`<br> (preview) | uint8_t (BOOLEAN) | Both | Globally enable the version negotiation extension for all client and server connections. |

## Registration Parameters

Expand All @@ -132,6 +134,7 @@ These parameters are accessed by calling [GetParam](./api/GetParam.md) or [SetPa
| `QUIC_PARAM_CONFIGURATION_TICKET_KEYS`<br> 1 | QUIC_TICKET_KEY_CONFIG[] | Set-only | Resumption ticket encryption keys. Server-side only. |
| `QUIC_PARAM_CONFIGURATION_VERSION_SETTINGS`<br> 2 | QUIC_VERSIONS_SETTINGS | Both | Change version settings for all connections on the configuration. |
| `QUIC_PARAM_CONFIGURATION_SCHANNEL_CREDENTIAL_ATTRIBUTE_W`<br> 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. |
| `QUIC_PARAM_CONFIGURATION_VERSION_NEG_ENABLED`<br> (preview) | uint8_t (BOOLEAN) | Both | Enables the version negotiation extension for all client connections on the configuration. |

## Listener Parameters

Expand Down
29 changes: 25 additions & 4 deletions docs/Versions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Configuring the QUIC versions on a MsQuic server is similar to configuring them

If a server is not in a fleet, or the operator/application does not ever need to change QUIC versions, then all three lists in `QUIC_VERSION_SETTINGS` **MUST** be the same.

If a server is deployed in a fleet, and the server operator wishes to change the supported QUIC versions, the Version Negotiation specification details how that should be done, quoted here:
If a server is deployed in a fleet, and the server operator wishes to change the supported QUIC versions, the [Version Negotiation specification](https://www.rfc-editor.org/rfc/rfc9368.html#section-5) details how that should be done, quoted here:
> When adding support for a new version:
> * The first step is to progressively add support for the new version to all server instances. This step updates the Acceptable Versions but not the Offered Versions nor the Fully-Deployed Versions. Once all server instances have been updated, operators wait for at least one MSL to allow any in-flight Version Negotiation packets to arrive.
> * Then, the second step is to progressively add the new version to Offered Versions on all server instances. Once complete, operators wait for at least another MSL.
Expand All @@ -70,7 +70,7 @@ If a server is deployed in a fleet, and the server operator wishes to change the
**Note that this opens connections to version downgrades (but only for partially-deployed versions) during the update window, since those could be due to clients communicating with both updated and non-updated server instances.**


### Configuring Versions via code
This snippet should execute before the server's `QUIC_CONFIGURATION` is created:
```c
QUIC_VERSION_SETTINGS Settings = { 0 };
Expand All @@ -92,9 +92,30 @@ MsQuic->SetParam(
&Settings);
```
### Configuring Versions via Windows Registry
MsQuic supports setting the Acceptable Versions, Offered Versions, and Fully-Deployed Versions lists via the Windows registry. These settings are global for all servers and clients on the machine.
The registry settings are overridden by settings specified in the code.
The registry values must be created under the `HKLM\System\CurrentControlSet\Services\MsQuic\Parameters` key.
Each list is stored in the registry as a `REG_BINARY` type, with the version numbers in little-endian (host) order.
The registry value for Acceptable Versions must be named `AcceptableVersions`.
The registry value for Offered Versions must be named `OfferedVersions`.
The registry value for Fully-Deployed Versions must be named `FullyDeployedVersions`.
Here's a sample .reg file that creates all three lists with QUIC version 2 first and QUIC version 1 after, in little endian order, and enables version negotiation:
```reg
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MsQuic\Parameters]
"AcceptableVersions"=hex:cf,43,33,6b,01,00,00,00
"OfferedVersions"=hex:cf,43,33,6b,01,00,00,00
"FullyDeployedVersions"=hex:cf,43,33,6b,01,00,00,00
"VersionNegotiationExtEnabled"=dword:00000001
```

# QUIC Version Negotiation Extension

The Version Negotiation Extension is on by default in our officially-released binaries. Since the standard is not yet complete, incompatible changes may be made preventing different drafts from working with each other. An application using MsQuic should be cautious about enabling the Version Negotiation Extension in production scenarios until the standard is complete.
The Version Negotiation Extension is off by default in our officially-released binaries, but can be enabled via registry or [Settings](./Settings.md).
The Version Negotiated Extension has been standardized and is present in MsQuic since version 2.3.

## Enabling Version Negotiation Extension on MsQuic Client

Expand All @@ -103,4 +124,4 @@ This setting **MUST** be set before [`ConnectionStart`](api/ConnectionStart.md)

## Enabling Version Negotiation Extension on MsQuic Server

Enabling the Version Negotiation Extension on server follows the same restrictions as setting the QUIC version on server, i.e. it **MUST** be set globally, using [`SetParam`](api/SetParam.md) before the `QUIC_CONFIGURATION` is opened for the server. It is set automatically when `QUIC_VERSION_SETTINGS` are set.
Enabling the Version Negotiation Extension on server follows the same restrictions as setting the QUIC version on server, i.e. it **MUST** be set globally, using [`SetParam`](api/SetParam.md) before the `QUIC_CONFIGURATION` is opened for the server. It is set automatically when `QUIC_VERSION_SETTINGS` are set, except via registry.

0 comments on commit 9587f74

Please sign in to comment.