Skip to content

Commit f6a0820

Browse files
author
Simonx Xu
authored
Merge pull request #9478 from v-lianna/CI_6853
AB#6853 Create virtual-shielded-host-guardian-service
2 parents 3153d4f + a1323dd commit f6a0820

File tree

2 files changed

+172
-0
lines changed

2 files changed

+172
-0
lines changed

‎support/windows-server/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2820,6 +2820,8 @@ items:
28202820
href: ./virtualization/troubleshoot-guarded-fabric-hgs.md
28212821
- name: Troubleshoot using the Guarded Fabric Diagnostic Tool
28222822
href: ./virtualization/troubleshoot-guarded-fabric-diagnostics.md
2823+
- name: Troubleshoot vTPM, shielded VM, and Host Guardian Service issues
2824+
href: ./virtualization/virtual-shielded-host-guardian-service.md
28232825
- name: Snapshots, checkpoints, and differencing disks
28242826
items:
28252827
- name: Can't delete a recovery checkpoint for a VM in DPM

‎support/windows-server/virtualization/virtual-shielded-host-guardian-service.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
title: Troubleshoot Virtual TPM, Shielded VM, and Host Guardian Service Issues
3+
description: Helps troubleshoot virtual TPM (vTPM), shielded virtual machine (VM), and Host Guardian Service (HGS) issues in Hyper-V clusters.
4+
ms.date: 09/01/2025
5+
manager: dcscontentpm
6+
audience: itpro
7+
ms.topic: troubleshooting
8+
ms.reviewer: kaushika, jeffhuge, v-lianna
9+
ms.custom:
10+
- sap:virtualization and hyper-v\shielded virtual machines
11+
- pcy:WinComm Storage High Avail
12+
ai-usage: ai-assisted
13+
---
14+
# Troubleshoot vTPM, shielded VM, and HGS issues in Hyper-V clusters
15+
16+
This guide provides a structured approach to resolving issues with virtual Trusted Platform Module (vTPM), shielded virtual machine (VM), and Host Guardian Service (HGS) in Hyper-V clusters. Always test changes in a nonproduction environment and maintain backups before implementing solutions. For unresolved issues, consult your hardware vendor or Microsoft support.
17+
18+
VTPM, shielded VM, and HGS are vital features in Hyper-V clusters, especially for ensuring secure virtual environments and compliance with modern operating system requirements, such as Windows 11. However, issues with these features can arise due to misconfigurations, hardware or firmware incompatibilities, or software errors. These problems might impact VM startup, migration, or security configuration, causing significant disruptions. This guide consolidates common scenarios, their causes, and resolutions to help restore secure VM operations efficiently.
19+
20+
## End-user and technical symptoms
21+
22+
- VMs with vTPM enabled fail to start or migrate between cluster nodes.
23+
- VMs remain operational only on their original hosts and can't fail over.
24+
- Shielded VMs can't start, migrate, or fail over.
25+
- Shield icons persist in management tools even after disabling shielding.
26+
- Attestation or key unwrap operations fail when using HGS over HTTPS.
27+
- VMs disappear from the cluster or management tools after cluster-aware updating or patching.
28+
- BitLocker enablement fails, or device encryption is reported as unsupported.
29+
- HGS attestation fails on all or some guarded hosts.
30+
- VMs fail to start after enabling TPM or upgrading the operating system.
31+
- Expanding an HGS cluster with nodes of differing hardware models fails.
32+
- Device encryption support reports errors such as "Feature is not available," "winre is not configured," or "hardware security test interface failed."
33+
34+
## Specific error messages and event IDs
35+
36+
- > Key protector could not be unwrapped.
37+
- > HGS cannot be an owner because it does not have private keys.
38+
- > Local security policy for virtual machine could not be generated automatically.
39+
40+
Error code: 0x80131500
41+
- > The computed authentication tag did not match the input authentication tag.
42+
43+
Error code: 0xC000A002
44+
- > The virtual machine doesn't have a key protector, and the key protector can't be added automatically in a guarded fabric.
45+
- > Invoke-CimMethod: [Function Name] failed using algorithm: Rsa.
46+
47+
HRESULT: 0x80131500
48+
- Event ID 2014, `Microsoft-Windows-HostGuardianService-Client/Admin`.
49+
- Event ID 57, `CertificateServicesClient-CertEnroll`, and Event ID 11, `Microsoft-Windows-CAPI2/Operational`.
50+
- "TransientError Host Unreachable" during HGS attestation/key unwrap.
51+
- "HasPrivateSigningKey = False" after guardian import.
52+
- Cluster logs showing "Catastrophic failure (0x8000FFFF)."
53+
54+
## Cause 1: Certificate and key protector issues
55+
56+
- Missing or mismatched certificates: vTPM and shielded VMs require signing and encryption certificates. Problems arise if certificates are missing or improperly restored during migration or export/import processes.
57+
- Untrusted or broken key protectors/guardians: Guardian misconfigurations or missing private keys can block VM operations.
58+
- Deleted or unrestored certificates: Shielded VM certificates that are accidentally deleted or not restored cause VMs to become nonoperational.
59+
- Certificate Subject Alternative Name (SAN) or trust issues: HGS over HTTPS fails if certificates lack the required SANs or if there are trust issues.
60+
61+
### Resolution: Certificate and key protector resolution
62+
63+
1. Export and import certificates with private keys:
64+
65+
- Export certificates from the source host using **certlm.msc** or PowerShell:
66+
67+
```powershell
68+
Export-PfxCertificate -Cert (Get-ChildItem -Path Cert:\LocalMachine\My<thumbprint>) -FilePath C:\path\to\export.pfx -Password (ConvertTo-SecureString -String '' -AsPlainText -Force)
69+
```
70+
71+
- Import certificates on the destination host:
72+
73+
```powershell
74+
Import-PfxCertificate -FilePath C:\path\to\export.pfx -CertStoreLocation Cert:\LocalMachine\My -Password (ConvertTo-SecureString -String '' -AsPlainText -Force)
75+
```
76+
77+
2. Regenerate key protectors:
78+
79+
```powershell
80+
$Owner = Get-HgsGuardian -Name "UntrustedGuardian"
81+
$KP = New-HgsKeyProtector -Owner $Owner -AllowUntrustedRoot
82+
Set-VMKeyProtector -VMName -KeyProtector $KP.RawData
83+
Enable-VMTPM -VMName
84+
```
85+
86+
3. Update signing and encryption certificates. Use `Set-VMKeyProtector` to assign the correct certificates.
87+
4. Resolve missing certificates. Create a new VM using the original VHDX file and configure the vTPM and key protector settings.
88+
89+
## Cause 2: TPM, hardware, driver, and firmware incompatibilities
90+
91+
- TPM model or firmware incompatibility: Earlier TPM models, such as HPE Gen9/Gen10, might lack support for required algorithms like RSAPSS.
92+
- Outdated storage drivers/firmware: Encryption features often require updated drivers and firmware.
93+
- Central processing unit (CPU) compatibility issues: Live migration might fail if CPU compatibility isn't configured across cluster nodes.
94+
95+
### Resolution: Firmware, driver, and hardware remediation
96+
97+
1. Update storage and TPM firmware. Work with hardware vendors to apply the latest updates.
98+
2. Check TPM support for required algorithms:
99+
100+
Verify RSAPSS support using:
101+
102+
```powershell
103+
Get-WmiObject -Namespace "Root\CIMV2\Security\MicrosoftTpm" -Class Win32_Tpm
104+
```
105+
106+
## Cause 3: Configuration and script errors
107+
108+
- Improper PowerShell script usage: Errors in automation scripts for enabling vTPM or shielded VM features can cause issues.
109+
- Misconfiguration in HGS or cluster setup: Problems occur when required Windows features aren't enabled or HGS registration is incorrect.
110+
- Mixing management tools: Concurrent modifications using tools like System Center Virtual Machine Manager (SCVMM), Failover Cluster Manager, and PowerShell can corrupt VM configurations.
111+
112+
### Resolution: Configuration, script, and management fixes
113+
114+
1. Correct PowerShell scripts. Ensure scripts appropriately handle vTPM enabling and verification.
115+
2. Fix VM configuration corruption. Re-create VM shells with existing VHDX files and reassign key protectors.
116+
3. Enable required Windows features:
117+
118+
```powershell
119+
Enable-WindowsOptionalFeature -Online -FeatureName IsolatedUserMode
120+
```
121+
122+
4. Maintain guarded fabric consistency. Import VMs onto hosts within the same guarded fabric.
123+
124+
## Cause 4: File system and cluster configuration corruption
125+
126+
- Corrupted `.vmcx` (VM configuration) files: Cluster-aware updating (CAU) or failovers might corrupt VM configuration files.
127+
- Guarded fabric/cluster node inconsistencies: Shielded VMs must be hosted on the same guarded fabric to function correctly.
128+
129+
### Resolution: Permissions, registry, and file system checks
130+
131+
1. Check file and folder permissions. Verify access rights for VM configurations and VHDX files.
132+
2. Validate registry settings. Confirm settings for virtualization-based security, TPM, and HGS.
133+
134+
## Cause 5: Networking and security protocol issues
135+
136+
- Networking changes/disruptions: Network reconfigurations can temporarily interrupt HGS attestation.
137+
- TLS/protocol mismatches: HGS might default to older TLS versions, and disabling TLS 1.0 without enabling TLS 1.2 can cause failures.
138+
139+
### Resolution: HGS attestation, protocol, and networking steps
140+
141+
1. Configure TLS protocols. Update registry settings to enable TLS 1.2 and disable TLS 1.0.
142+
2. Resolve HTTPS certificate issues. Ensure certificates include the required SANs for all nodes.
143+
3. Troubleshoot attestation failures. Test network connectivity using `Test-NetConnection`.
144+
145+
## Cause 6: Supportability and documentation gaps
146+
147+
- Unsupported HGS cluster expansion: Adding nodes with differing hardware models to an HGS cluster is unsupported.
148+
- Documentation gaps: Lack of guidance for certain PowerShell or WMI methods can lead to configuration errors.
149+
150+
### Resolution: Best practices and documentation
151+
152+
1. HGS cluster expansion: Add only identical hardware nodes to HGS clusters.
153+
2. Shielding existing VMs: Use WMI's `PrepareSpecializedMachine` method to shield VMs.
154+
155+
## Data collection
156+
157+
To gather data for troubleshooting:
158+
159+
- Collect logs via Event Viewer (Application, System, CAPI2, HostGuardianService-Client).
160+
- Generate cluster logs:
161+
162+
```powershell
163+
Get-ClusterLog -Destination
164+
```
165+
166+
- Use network diagnostic tools like `Test-NetConnection` and Wireshark.
167+
168+
## Reference
169+
170+
[PrepareSpecializedMachine method of the Msps_ProvisioningService class](/previous-versions/windows/desktop/mspsserviceprov/msps-provisioningservice-preparespecializedmachine)

0 commit comments

Comments
 (0)