Skip to content

Commit ddf350a

Browse files
v-liannav-lianna
committed
AB#6853 Create virtual-shielded-host-guardian-service
1 parent b3ad870 commit ddf350a

2 files changed

Lines changed: 153 additions & 0 deletions

File tree

‎support/windows-server/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2798,6 +2798,8 @@ items:
27982798
href: ./virtualization/troubleshoot-guarded-fabric-hgs.md
27992799
- name: Troubleshoot using the Guarded Fabric Diagnostic Tool
28002800
href: ./virtualization/troubleshoot-guarded-fabric-diagnostics.md
2801+
- name: Troubleshoot vTPM, shielded VM, and Host Guardian Service issues
2802+
href: ./virtualization/virtual-shielded-host-guardian-service.md
28012803
- name: Snapshots, checkpoints, and differencing disks
28022804
items:
28032805
- name: Can't delete a recovery checkpoint for a VM in DPM

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

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: Troubleshoot VTPM, Shielded VM, and Host Guardian Service Issues
3+
description: Helps troubleshoot Virtual TPM (vTPM), shielded VM, and Host Guardian Service (HGS) issues in Hyper-V clusters.
4+
ms.date: 08/06/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+
# Troubleshooting Virtual TPM (vTPM), Shielded VM, and Host Guardian Service (HGS) Issues in Hyper-V Clusters
15+
16+
Virtual TPM (vTPM), Shielded VM, and Host Guardian Service (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 may 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.
17+
18+
## Symptoms
19+
20+
### End-user and technical symptoms
21+
22+
- Virtual machines (VMs) with vTPM enabled fail to start or migrate between cluster nodes.
23+
- VMs remain operational only on their original host and cannot fail over.
24+
- Shielded VMs cannot 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 with HTTPS.
27+
- VMs disappear from the cluster or management tools after cluster-aware updating or patching.
28+
- BitLocker enablement fails, or device encryption reports 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 the 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." (Error Code: 0x80131500)
39+
- "The computed authentication tag did not match the input authentication tag." (Error Code: 0xC000A002)
40+
- "The virtual machine doesn’t have a key protector, and the key protector can’t be added automatically in a guarded fabric."
41+
- "Invoke-CimMethod : [Function Name] failed using algorithm: Rsa." (HRESULT: 0x80131500)
42+
- Event ID 2014, Microsoft-Windows-HostGuardianService-Client/Admin.
43+
- Event ID 57, CertificateServicesClient-CertEnroll, and Event ID 11, Microsoft-Windows-CAPI2/Operational.
44+
- "TransientError Host Unreachable" during HGS attestation/key unwrap.
45+
- "HasPrivateSigningKey = False" after guardian import.
46+
- Cluster logs showing "Catastrophic failure (0x8000FFFF)."
47+
48+
## Cause
49+
50+
### 1. Certificate and key protector issues
51+
52+
- **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.
53+
- **Untrusted or broken key protectors/guardians**: Guardian misconfigurations or missing private keys can block VM operations.
54+
- **Deleted or unrestored certificates**: Shielded VM certificates that are accidentally deleted or not restored render VMs non-operational.
55+
- **Certificate SAN or trust issues**: HGS over HTTPS fails if certificates lack required Subject Alternative Names (SANs) or if there are trust issues.
56+
57+
### 2. TPM, hardware, driver, and firmware incompatibilities
58+
59+
- **TPM model or firmware incompatibility**: Older TPM models, such as HPE Gen9/Gen10, may lack support for required algorithms like RSAPSS.
60+
- **Outdated storage drivers/firmware**: Encryption features often require updated drivers and firmware.
61+
- **CPU compatibility issues**: Live migration may fail if CPU compatibility is not configured across cluster nodes.
62+
63+
### 3. Configuration and script errors
64+
65+
- **Improper PowerShell script usage**: Errors in automation scripts for enabling vTPM or Shielded VM features can create issues.
66+
- **Misconfiguration in HGS or cluster setup**: Problems occur when required Windows features are not enabled, or HGS registration is incorrect.
67+
- **Mixing management tools**: Concurrent modifications using tools like System Center Virtual Machine Manager (SCVMM), Failover Cluster Manager, and PowerShell can corrupt VM configurations.
68+
69+
### 4. File system and cluster configuration corruption
70+
71+
- **Corrupted .vmcx (VM configuration) files**: Cluster-aware updating (CAU) or failovers may corrupt VM configuration files.
72+
- **Guarded fabric/cluster node inconsistencies**: Shielded VMs must be hosted on the same guarded fabric to function correctly.
73+
74+
### 5. Networking and security protocol issues
75+
76+
- **Networking changes/disruptions**: Network reconfigurations can temporarily interrupt HGS attestation.
77+
- **TLS/protocol mismatches**: HGS may default to older TLS versions, and disabling TLS 1.0 without enabling TLS 1.2 can cause failures.
78+
79+
### 6. Supportability and documentation gaps
80+
81+
- **Unsupported HGS cluster expansion**: Adding nodes with differing hardware models to an HGS cluster is unsupported.
82+
- **Documentation gaps**: Lack of guidance for certain PowerShell or WMI methods can lead to configuration errors.
83+
84+
## Resolution
85+
86+
### A. Certificate and key protector resolution
87+
88+
1. **Export and import certificates with private keys**: - Export certificates from the source host using certlm.msc or PowerShell:
89+
90+
Export-PfxCertificate -Cert (Get-ChildItem -Path Cert:\LocalMachine\My<thumbprint>) -FilePath C:\path\to\export.pfx -Password (ConvertTo-SecureString -String '' -AsPlainText -Force)
91+
- Import certificates on the destination host:
92+
93+
Import-PfxCertificate -FilePath C:\path\to\export.pfx -CertStoreLocation Cert:\LocalMachine\My -Password (ConvertTo-SecureString -String '' -AsPlainText -Force)
94+
2. **Regenerate key protectors**:
95+
96+
$Owner = Get-HgsGuardian -Name "UntrustedGuardian"
97+
$KP = New-HgsKeyProtector -Owner $Owner -AllowUntrustedRoot
98+
Set-VMKeyProtector -VMName -KeyProtector $KP.RawData
99+
Enable-VMTPM -VMName
100+
3. **Update signing and encryption certificates**:Use Set-VMKeyProtector to assign the correct certificates.
101+
4. **Resolve missing certificates**:Create a new VM using the original VHDX file and configure vTPM and key protector.
102+
103+
### B. Firmware, driver, and hardware remediation
104+
105+
1. **Update storage and TPM firmware**:Work with hardware vendors to apply the latest updates.
106+
2. **Check TPM support for required algorithms**:
107+
Verify RSAPSS support using:
108+
109+
Get-WmiObject -Namespace "Root\CIMV2\Security\MicrosoftTpm" -Class Win32_Tpm
110+
111+
### C. Configuration, script, and management fixes
112+
113+
1. **Correct PowerShell scripts**:Ensure scripts appropriately handle vTPM enabling and verification.
114+
2. **Fix VM configuration corruption**:Recreate VM shells with existing VHDX files and reassign key protectors.
115+
3. **Enable required Windows features**:
116+
117+
Enable-WindowsOptionalFeature -Online -FeatureName IsolatedUserMode
118+
4. **Maintain guarded fabric consistency**:Import VMs onto hosts within the same guarded fabric.
119+
120+
### D. HGS attestation, protocol, and networking steps
121+
122+
1. **Configure TLS protocols**:Update registry settings to enable TLS 1.2 and disable TLS 1.0.
123+
2. **Resolve HTTPS certificate issues**:Ensure certificates include required SANs for all nodes.
124+
3. **Troubleshoot attestation failures**:Test network connectivity using Test-NetConnection.
125+
126+
### E. Permissions, registry, and file system checks
127+
128+
1. **Check file and folder permissions**:Verify access rights for VM configurations and VHDX files.
129+
2. **Validate registry settings**:Confirm settings for virtualization-based security, TPM, and HGS.
130+
131+
### F. Best practices and documentation
132+
133+
1. **HGS cluster expansion**:Add only identical hardware nodes to HGS clusters.
134+
2. **Shielding existing VMs**:Use WMI’s PrepareSpecializedMachine method to shield VMs.
135+
136+
## Data collection
137+
138+
To gather data for troubleshooting:
139+
140+
- Collect logs via Event Viewer (Application, System, CAPI2, HostGuardianService-Client).
141+
- Generate cluster logs:
142+
143+
Get-ClusterLog -Destination
144+
- Use network diagnostic tools like Test-NetConnection and Wireshark.
145+
146+
## References
147+
148+
- [PrepareSpecializedMachine Method](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/mspsserviceprov/msps-provisioningservice-preparespecializedmachine)
149+
- Hyper-V and HGS official documentation on configuration and troubleshooting.
150+
151+
This guide provides a structured approach to resolving issues with vTPM, Shielded VM, and HGS in Hyper-V clusters. Always test changes in a non-production environment and maintain backups before implementing solutions. For unresolved issues, consult your hardware vendor or Microsoft support.

0 commit comments

Comments
 (0)