Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve version deployment documentation #4646

Merged
merged 2 commits into from
Nov 6, 2024
Merged

Improve version deployment documentation #4646

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
240e491
Improve version deployment documentation
anrossi Nov 5, 2024
3b4df79
Address comments.
anrossi Nov 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/Deployment.md
View file
Open in desktop
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
Open in desktop
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 |
anrossi marked this conversation as resolved.
Show resolved Hide resolved
|-----------------------------------|------------|------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------|
| 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
Open in desktop
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know it doesn't work this way today, but I think it's worth updating the settings code (in a future PR) to handle a more simpler configuration model, where only one of these has to be implemented; including the Enabled one. Thoughts?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the risk of a single-list is that a deployment is made using the single-list model, and then we add QUIC 3 support, and the deployment either does the version rollout wrong, or the infrastructure isn't built to do the rollout, so they have to spend more time updating infrastructure and testing it to even do a rollout.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do think that setting any version list via registry should enable the version negotiation extension without the extra registry value.

"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.
Loading