Skip to content

Commit d69f5a3

Browse files
v-liannav-lianna
committed
Create linux-virtual-machine-issue-hyper-v.md
1 parent 04a9494 commit d69f5a3

1 file changed

Lines changed: 138 additions & 0 deletions

File tree

‎support/windows-server/virtualization/linux-virtual-machine-issue-hyper-v.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
title: Troubleshoot Linux Virtual Machine Issues on Hyper-V
3+
description: Provides a comprehensive guide to diagnosing and resolving common issues encountered when deploying and managing Linux virtual machines (VMs) on Microsoft Hyper-V environments.
4+
ms.date: 08/05/2025
5+
manager: dcscontentpm
6+
audience: itpro
7+
ms.topic: troubleshooting
8+
ms.reviewer: kaushika, jeffhugh, v-lianna
9+
ms.custom:
10+
- sap:virtualization and hyper-v\integration components
11+
- pcy:WinComm Storage High Avail
12+
---
13+
# Troubleshooting Linux Virtual Machine Issues on Hyper-V
14+
15+
This article provides a comprehensive guide to diagnosing and resolving common issues encountered when deploying and managing Linux virtual machines (VMs) on Microsoft Hyper-V environments. These issues may include installation challenges, live migration failures, time synchronization problems, missing VM information in management consoles, CPU compatibility discrepancies, and licensing or support inquiries. Resolving these problems is critical for ensuring reliability, compatibility, and optimal performance of Linux workloads in Hyper-V infrastructures.
16+
17+
## Symptoms
18+
19+
### Common issues observed in Linux VMs on Hyper-V
20+
21+
- **VM installation and boot issues**: - Linux OS installations, such as SUSE Linux Enterprise Server (SLES) 15 SP5, stall or fail on Generation 2 VMs but succeed on Generation 1.
22+
- Installation menus appear, but the process cannot complete.
23+
- **Live migration and VM state errors**: - Specific Ubuntu-based or vendor-supplied Linux VMs fail to migrate, with errors occurring at 58–68% completion.
24+
- Error message: "Cannot restore this virtual machine because the saved state data cannot be read. Delete the saved state data and then try to start the virtual machine. (0xC0370027)."
25+
- Event ID: **21502** in Hyper-V logs.
26+
- Additional error codes: **0x80048054** and **0x80070037**.
27+
- **Management console and integration data issues**: - Linux VM IP addresses and hostnames are not visible in Hyper-V Manager, System Center Virtual Machine Manager (SCVMM), or other management consoles.
28+
- Integration Services are installed and configured, but data remains missing.
29+
- **Time synchronization issues**: - Linux VM system time does not sync with the Hyper-V host.
30+
- Time zone inconsistencies are observed on the VM’s real-time clock (RTC), causing application time drift.
31+
- **CPU feature/instruction set issues**: - Missing CPU flags, such as sse4_2, inside Linux VMs (cat /proc/cpuinfo).
32+
- Applications or tools fail due to missing CPU instructions.
33+
- **Frequent VM disconnects**: - Linux VMs, especially Red Hat Enterprise Linux (RHEL)-based, frequently disconnect from the Hyper-V console.
34+
- Error messages appear when connecting via Hyper-V Manager.
35+
- **Licensing, support, and feature inquiries**: - Questions about licensing non-Windows operating systems on Windows Server Standard/Datacenter.
36+
- Inquiries about support for legacy Linux versions or Oracle Database workloads.
37+
- Questions regarding Windows Subsystem for Linux 2 (WSL2) support and nested virtualization requirements.
38+
39+
## Cause
40+
41+
### Root causes categorized by issue type
42+
1. **Configuration and compatibility**: - **Generation 2 VM incompatibility**: Certain Linux distributions require specific Generation 2 Hyper-V settings, such as Secure Boot or UEFI, for successful installation.
43+
- **Unsupported Linux versions**: Older or unlisted Linux versions may not work with Hyper-V integration components, leading to missing data or failed operations.
44+
- **Licensing and support gaps**: Documentation may not cover all scenarios for OS/distribution/version compatibility.
45+
2. **Integration services and VM data reporting**: - **Missing or misconfigured Integration Services**: Without proper configuration, Linux Integration Services may fail to report data like IP addresses and hostnames.
46+
- **Console/SCVMM sync issues**: Synchronization delays or database errors may prevent updated VM data from displaying.
47+
3. **File/state corruption and migration failures**: - **Corrupted VMRS files**: Migration issues may arise if VM saved state or runtime files are corrupted.
48+
- **File permission problems**: Insufficient permissions or locked files related to the VM can block migration or restoration.
49+
4. **Guest OS settings and platform differences**: - **RTC and time zone handling**: Hyper-V provides system time to the guest RTC without time zone metadata; guest OS settings determine interpretation.
50+
- **CPU compatibility mode**: Enabling this mode restricts available CPU instructions for the guest, causing feature gaps.
51+
5. **External or unsupported scenarios**: - **Application/OS-specific issues**: Problems within guest OS or applications, like Oracle Database, require vendor support.
52+
- **Feature or environment limitations**: Advanced features, such as nested virtualization and WSL2, need specific VM configurations or hardware.
53+
54+
## Resolution
55+
56+
### 1. Resolving VM installation issues (Generation 2 Linux VMs)
57+
1. **Review VM configuration**: - Disable Secure Boot or set it to use the correct template (e.g., MicrosoftUEFICertificateAuthority for supported Linux distributions).
58+
- Ensure the VM generation matches the Linux distribution’s requirements.
59+
2. **Adjust VM settings**: - Set the firmware to boot from the correct device (DVD or ISO).
60+
- Remove unnecessary hardware, such as legacy network adapters.
61+
3. **Retry installation**: - Reattempt the OS installation after making the necessary changes.
62+
4. **Workaround**: - If issues persist, install the OS on a Generation 1 VM.
63+
64+
### 2. Resolving live migration and state file errors
65+
1. **Check event logs and error codes**: - Review Hyper-V logs for Event ID **21502** and error codes such as **0xC0370027**, **0x80048054**, or **0x80070037**.
66+
2. **Inspect VM state files**: - Ensure .vmrs and .vmcx files are accessible on both source and destination nodes.
67+
3. **Create a new VM**: - Shut down the affected VM.
68+
- Create a new VM and attach the original OS/data disks. Match CPU and RAM settings to the original configuration.
69+
4. **Test migration**: - Attempt live migration with the new VM.
70+
5. **Monitor for recurrence**: - If resolved, continue monitoring the VM. If the issue persists, escalate for further disk or file system investigation.
71+
72+
### 3. Resolving management console and integration data issues
73+
1. **Verify Integration Services**: - Use the command lsmod | grep hv in the guest OS to confirm that Hyper-V modules are loaded.
74+
- Ensure the latest Linux Integration Services are installed.
75+
2. **Enable data exchange**: - In VM settings, ensure "Data Exchange" is enabled under Integration Services.
76+
3. **Update management console**: - Apply the latest updates to Hyper-V, SCVMM, or other management platforms.
77+
4. **Correct SCVMM database**(if needed): - Backup the SCVMM database.
78+
- Use SQL queries to update missing VM names or IPs.
79+
80+
### 4. Resolving time synchronization issues
81+
1. **Update Integration Services**: - Ensure the guest OS has the latest Linux Integration Services installed.
82+
2. **Verify time sync settings**: - In Hyper-V Manager, ensure "Time Synchronization" is enabled.
83+
3. **Adjust guest OS settings**: - Use timedatectl to configure the system clock and time zone correctly. For example: timedatectl set-timezone UTC.
84+
4. **Delay application startup**: - For time-sensitive applications, delay startup until synchronization completes.
85+
86+
### 5. Resolving CPU feature/instruction set issues
87+
1. **Disable CPU compatibility mode**: - In Hyper-V Manager or via PowerShell:
88+
89+
Set-VMProcessor -VMName -CompatibilityForMigrationEnabled $false
90+
2. **Validate in guest OS**: - Run cat /proc/cpuinfo to confirm that required CPU flags are present.
91+
3. **Restart VM**: - Restart the VM to apply changes.
92+
93+
### 6. Resolving frequent VM disconnects
94+
1. **Check network and VM health**: - Verify that network adapters are correctly configured and functioning.
95+
2. **Review VM cloning practices**: - Ensure unique MAC addresses and proper cleanup after cloning.
96+
3. **Adjust Secure Boot settings**: - Enable or disable Secure Boot as required by the Linux distribution.
97+
4. **Contact Linux vendor support**: - Escalate issues that persist to the Linux distribution vendor.
98+
99+
### 7. Resolving licensing, support, and feature inquiries
100+
1. **Licensing questions**: - Consult Microsoft licensing specialists for queries about licensing non-Windows OSes on Windows Server.
101+
2. **Legacy OS or unsupported features**: - Refer to the relevant vendor for support on legacy Linux versions, Oracle Database, or WSL2.
102+
3. **Nested virtualization**: - Confirm that your VM size or hardware supports nested virtualization.
103+
104+
## Data collection
105+
106+
To assist in troubleshooting, gather the following logs and information:
107+
- **VML traces** (for live migration):
108+
109+
VmlTrace.exe /m a /f all all
110+
VmlTrace.exe stop
111+
112+
```plaintext
113+
 
114+
```
115+
- **NetSH network trace**:
116+
117+
netsh trace start capture=yes tracefile=network-trace.etl overwrite=yes persistent=yes
118+
netsh trace stop
119+
120+
```plaintext
121+
 
122+
```
123+
- **Integration Services check**:
124+
125+
Get-VMIntegrationService -VMName
126+
- **CPU validation**:
127+
128+
cat /proc/cpuinfo
129+
- **Time settings** (Linux):
130+
131+
timedatectl status
132+
timedatectl set-timezone
133+
134+
## References
135+
- [Supported Linux and FreeBSD Virtual Machines on Hyper-V](https://learn.microsoft.com/en-us/windows-server/virtualization/hyper-v/supported-centos-and-red-hat-enterprise-linux-virtual-machines-on-hyper-v)
136+
- [Linux Integration Services Documentation](https://learn.microsoft.com/en-us/windows-server/virtualization/hyper-v/supported-debian-virtual-machines-on-hyper-v)
137+
138+
If issues persist after following these steps, collect the relevant logs and contact Microsoft Support or your Linux distribution vendor for further assistance.

0 commit comments

Comments
 (0)