Skip to content

Change to hostid hash generation docs #8364

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

Merged
DavidBoike merged 1 commit into from
Jun 23, 2026
+41 −43
Merged

Change to hostid hash generation docs #8364

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
40 changes: 0 additions & 40 deletions nservicebus/compliance/fips_host-id-generation_core_[10,).partial.md
View file
Open in desktop

This file was deleted.

28 changes: 28 additions & 0 deletions nservicebus/compliance/fips_host-id-generation_core_[10,11).partial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
## NServiceBus

@DavidBoike DavidBoike Jun 22, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Shown as a delete/add but really a rename. When NServiceBus 11 is released, from the context of the FIPS article, XxHash128 is already the default so there's nothing to worry about, so this whole partial goes away.


Starting in version 10.2, NServiceBus can use a non-cryptographic hash algorithm (XxHash128) to generate deterministic unique identifiers for endpoints, also known as host identifiers (HostIds). Because XxHash128 is not a cryptographic algorithm, FIPS policy enforcement does not block host identifier generation; the host ID workaround described below is no longer needed.

To ensure the non-cryptographic hash is used in NServiceBus 10, set the following AppContext switch before endpoint startup:

```csharp
AppContext.SetSwitch("NServiceBus.Core.Hosting.UseV2DeterministicGuid", true);
```

Or via environment variable:

```text
DOTNET_NServiceBus_Core_Hosting_UseV2DeterministicGuid=true
```

Or via MSBuild in a project file:

```xml
<ItemGroup>
<RuntimeHostConfigurationOption Include="NServiceBus.Core.Hosting.UseV2DeterministicGuid" Value="true" />
</ItemGroup>
```

> [!WARNING]
> Changing the host identifier algorithm changes the host ID that identifies an endpoint in ServicePulse and ServiceControl. Changes to the algorithm will cause existing known endpoints to appear inactive in the ServicePulse [heartbeats](/monitoring/heartbeats/in-servicepulse.md) and [monitoring](/monitoring/metrics/in-servicepulse.md) views while new instances (with the changed host identifiers) appear in their place. Stale instances should be [removed from the monitoring view](/monitoring/metrics/in-servicepulse.md#disconnected-endpoints-removing-disconnected-endpoints).
>
> See the [NServiceBus version 10 to 11 upgrade guide](/nservicebus/upgrades/10to11/#host-identifier-algorithm-change) for more information on migrating from MD5 to the XxHash128 hash algorithm.

@DavidBoike DavidBoike Jun 22, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Warning attempts to more clearly show what is going to happen if you change during the 10 timeframe, and routes all other upgrade concerns to the upgrade guide.

16 changes: 13 additions & 3 deletions nservicebus/upgrades/10to11/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,13 +196,23 @@ The following APIs are deprecated:

## Host identifier algorithm change

In version 11, the default algorithm for generating deterministic host identifiers changes from MD5 to XxHash128 (RFC 9562 version 8 GUIDs). This produces different host identifiers, which affects how endpoints are identified in [ServicePulse](/servicepulse/) and [ServiceControl](/servicecontrol/).
In version 11, the default algorithm for generating deterministic host identifiers changes from MD5 to XxHash128 (RFC 9562 version 8 GUIDs). This produces different host identifiers, which affects how endpoints are identified in [ServicePulse](/servicepulse/) and [ServiceControl](/servicecontrol/). Changing the algorithm will cause existing known endpoints to appear inactive in the ServicePulse [heartbeats](/monitoring/heartbeats/in-servicepulse.md) and [monitoring](/monitoring/metrics/in-servicepulse.md) views, while new instances (with the changed host identifiers) appear in their place.

### Rationale

This change provides a path for customers who require **FIPS-compliant** host identifiers (see [FIPS compliance](/nservicebus/compliance/fips.md)). The legacy MD5-based algorithm is not FIPS-compliant; by moving to the new `XxHash128` algorithm, the framework uses a compliant standard by default.

To ensure a predictable transition, this is designed as a multi-phase migration. In version 11, the new algorithm becomes the default. By making this an explicit switch rather than an automatic change, there is a clear "escape hatch" to preserve legacy host IDs if correlation with older monitoring data (such as ServicePulse) must be maintained during the transition.
To ensure a predictable transition, this is designed as a multi-phase migration:

@DavidBoike DavidBoike Jun 22, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Introduce the table as a (hopefully) easily consumable overview of what is going to happen in each version


| NServiceBus Versions | Hashes Available | Default Hash | App Switch |
|:-:|:-:|:-:|:-:|
| <= 10.2 | MD5 Only | MD5 | - |
| >= 10.2 && < 11.0 | MD5 + XxHash128 | MD5 | Can opt in |
| >= 11.0 && < 12.0 | MD5 + XxHash128 | XxHash128 | Can opt out |
| >= 12.0 | XxHash128 Only | XxHash128 | - |


In version 11, XxHash128 becomes the default. By making this an explicit switch rather than an automatic change, there is a clear "escape hatch" to preserve legacy host IDs if correlation with older monitoring data (such as ServicePulse) must be maintained during the transition.

This approach allows the framework to move toward a compliant default while providing the necessary flexibility to manage existing integrations before the legacy algorithm is removed in version 12.

Expand All @@ -218,7 +228,7 @@ To preserve the existing MD5-based host identifier after upgrading, set the foll
AppContext.SetSwitch("NServiceBus.Core.Hosting.UseV2DeterministicGuid", false);
```

Or via environment variable (.NET 9+):

@DavidBoike DavidBoike Jun 22, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

We're talking about NServiceBus 10+ which is already forcing .NET 10+ so that detail seems potentially confusing.

Or via environment variable:

```text
DOTNET_NServiceBus_Core_Hosting_UseV2DeterministicGuid=false
Expand Down