Skip to content

Commit 6a77876

Browse files
author
Simonx Xu
authored
Merge pull request #9469 from v-lianna/CI_6849
AB#6849 Create linux-virtual-machine-issue-hyper-v.md
2 parents 45fb7bf + f16b3e8 commit 6a77876

File tree

2 files changed

+203
-0
lines changed

2 files changed

+203
-0
lines changed

‎support/windows-server/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2778,6 +2778,8 @@ items:
27782778
href: ./virtualization/degraded-integration-services-message.md
27792779
- name: Hyper-V Time Synchronization doesn't adjust the VM system clock
27802780
href: ./virtualization/virtual-machine-time-not-synced.md
2781+
- name: Troubleshoot Linux virtual machine issues on Hyper-V
2782+
href: ./virtualization/linux-virtual-machine-issue-hyper-v.md
27812783
- name: Unknown devices in Device manager
27822784
href: ./virtualization/unknown-device-vmbus-virtual-machine.md
27832785
- name: Uptime value of Hyper-V Management console changes to the resume time

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

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
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 VMs in Microsoft Hyper-V environments.
4+
ms.date: 09/01/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+
# Troubleshoot Linux virtual machine issues on Hyper-V
14+
15+
This article provides a comprehensive guide to diagnosing and resolving common issues in deploying and managing Linux virtual machines (VMs) in Microsoft Hyper-V environments.
16+
17+
These issues might include installation challenges, live migration failures, time synchronization problems, missing VM information in management consoles, central processing unit (CPU) compatibility discrepancies, and licensing or support inquiries. Resolving these issues is critical to ensuring the reliability, compatibility, and optimal performance of Linux workloads in Hyper-V infrastructures.
18+
19+
## Common issues observed in Linux VMs on Hyper-V
20+
21+
- VM installation and boot issues:
22+
23+
- Installations of a Linux operating system (OS), such as SUSE Linux Enterprise Server (SLES) 15 SP5, stall or fail on Generation 2 VMs but succeed on Generation 1 VMs.
24+
- Installation menus appear, but the process fails to complete.
25+
26+
- Live migration and VM state errors:
27+
28+
- Specific Ubuntu-based or vendor-supplied Linux VMs fail to migrate, with errors occurring between 58% and 68% completion.
29+
- Error message: "Cannot restore this virtual machine because the saved state data can't be read. Delete the saved state data and then try to start the virtual machine. (0xC0370027)."
30+
- Event ID 21502 in Hyper-V logs.
31+
- Additional error codes 0x80048054 and 0x80070037.
32+
33+
- Management console and integration data issues:
34+
35+
- Linux VM IP addresses and hostnames aren't visible in Hyper-V Manager, System Center Virtual Machine Manager (SCVMM), or other management consoles.
36+
- Integration services are installed and configured, but the data is still missing.
37+
38+
- Time synchronization issues:
39+
40+
- Linux VM system time doesn't synchronize with the Hyper-V host.
41+
- Time zone inconsistencies are observed on the VM's real-time clock (RTC), causing application time drift.
42+
43+
- CPU feature/instruction set issues:
44+
45+
- Missing CPU flags, such as `sse4_2`, inside Linux VMs (`cat /proc/cpuinfo`).
46+
- Applications or tools fail due to missing CPU instructions.
47+
48+
- Frequent VM disconnections:
49+
50+
- Linux VMs, especially those based on Red Hat Enterprise Linux (RHEL), frequently disconnect from the Hyper-V console.
51+
- Error messages appear when connecting via Hyper-V Manager.
52+
53+
- Licensing, support, and feature inquiries:
54+
55+
- Questions about licensing non-Windows operating systems on Windows Server Standard/Datacenter.
56+
- Inquiries about support for legacy Linux versions or Oracle Database workloads.
57+
- Questions regarding Windows Subsystem for Linux 2 (WSL2) support and nested virtualization requirements.
58+
59+
## Root causes categorized by issue type
60+
61+
- Configuration and compatibility:
62+
63+
- Generation 2 VM incompatibility: Certain Linux distributions require specific Generation 2 Hyper-V settings, such as Secure Boot or UEFI, for successful installation.
64+
- Unsupported Linux versions: Earlier or unlisted Linux versions might not work with Hyper-V integration components, leading to data loss or operational failures.
65+
- Licensing and support gaps: Documentation might not cover all scenarios for OS/distribution/version compatibility.
66+
67+
- Integration services and VM data reporting:
68+
69+
- Missing or misconfigured integration services: Without proper configuration, Linux integration services might fail to report data like IP addresses and hostnames.
70+
- Console/SCVMM synchronization issues: Synchronization delays or database errors might prevent updated VM data from being displayed.
71+
72+
- File/state corruption and migration failures:
73+
74+
- Corrupted VMRS files: Migration issues might arise if VM saved state or runtime files are corrupted.
75+
- File permission problems: Insufficient permissions or locked files related to the VM can block migration or restoration.
76+
77+
- Guest OS settings and platform differences:
78+
79+
- RTC and time zone handling: Hyper-V provides the system time to the guest RTC without time zone metadata; the guest OS settings determine the interpretation.
80+
- CPU compatibility mode: Enabling this mode restricts available CPU instructions for the guest, causing feature gaps.
81+
82+
- External or unsupported scenarios:
83+
84+
- Application/OS-specific issues: Problems within guest OS or applications, like Oracle Database, require vendor support.
85+
- Feature or environment limitations: Advanced features, such as nested virtualization and WSL2, need specific VM configurations or hardware.
86+
87+
## Resolve VM installation issues (Generation 2 Linux VMs)
88+
89+
1. Review the VM configuration:
90+
91+
- Disable Secure Boot or set it to use the correct template (for example, `MicrosoftUEFICertificateAuthority` for supported Linux distributions).
92+
- Ensure the VM generation matches the Linux distribution's requirements.
93+
94+
2. Adjust VM settings:
95+
96+
- Set the firmware to boot from the correct device (DVD or ISO).
97+
- Remove unnecessary hardware, such as legacy network adapters.
98+
99+
3. Retry the OS installation after making the necessary changes.
100+
4. If issues persist, install the OS on a Generation 1 VM.
101+
102+
## Resolve live migration and state file errors
103+
104+
1. Check event logs and error codes. Review Hyper-V logs for Event ID 21502 and error codes such as 0xC0370027, 0x80048054, or 0x80070037.
105+
2. Inspect VM state files. Ensure `.vmrs` and `.vmcx` files are accessible on both the source and destination nodes.
106+
3. Create a new VM:
107+
108+
1. Shut down the affected VM.
109+
2. Create a new VM and attach the original OS/data disks. Match the CPU and RAM settings to the original configuration.
110+
111+
4. Test migration. Perform a live migration with the new VM.
112+
5. Monitor for recurrence. If the issue is resolved, continue monitoring the VM. If the issue persists, escalate for further disk or file system investigation.
113+
114+
## Resolve management console and integration data issues
115+
116+
1. Verify integration services:
117+
118+
- Use the `lsmod | grep hv` command in the guest OS to confirm that Hyper-V modules are loaded.
119+
- Ensure the latest Linux integration services are installed.
120+
121+
2. Enable data exchange. In the VM settings, ensure "Data Exchange" is enabled under integration services.
122+
3. Update the management console. Apply the latest updates to Hyper-V, SCVMM, or other management platforms.
123+
4. Correct the SCVMM database (if needed):
124+
125+
1. Back up the SCVMM database.
126+
2. Use SQL queries to update missing VM names or IP addresses.
127+
128+
## Resolve time synchronization issues
129+
130+
1. Update integration services. Ensure the guest OS has the latest Linux integration services installed.
131+
2. Verify time synchronization settings. In Hyper-V Manager, ensure "Time Synchronization" is enabled.
132+
3. Adjust guest OS settings. Use `timedatectl` to configure the system clock and time zone correctly. For example, `timedatectl set-timezone UTC`.
133+
4. Delay application startup. For time-sensitive applications, delay startup until synchronization completes.
134+
135+
## Resolve CPU feature/instruction set issues
136+
137+
1. Disable CPU compatibility mode in Hyper-V Manager or via PowerShell:
138+
139+
```powershell
140+
Set-VMProcessor -VMName -CompatibilityForMigrationEnabled $false
141+
```
142+
143+
2. Validate in the guest OS. Run `cat /proc/cpuinfo` to confirm that the required CPU flags are present.
144+
3. Restart the VM to apply the changes.
145+
146+
## Resolve frequent VM disconnections
147+
148+
1. Check network and VM health. Verify that network adapters are correctly configured and functioning.
149+
2. Review VM cloning practices. Ensure unique MAC addresses and proper cleanup after cloning.
150+
3. Adjust Secure Boot settings. Enable or disable Secure Boot as required by the Linux distribution.
151+
4. Contact Linux vendor support. Escalate issues that persist to the Linux distribution vendor.
152+
153+
## Resolve licensing, support, and feature inquiries
154+
155+
- Licensing questions: Consult Microsoft licensing specialists for queries about licensing non-Windows operating systems on Windows Server.
156+
- Legacy OS or unsupported features: Refer to the relevant vendor for support on legacy Linux versions, Oracle Database, or WSL2.
157+
- Nested virtualization: Confirm that your VM size or hardware supports nested virtualization.
158+
159+
## Data collection
160+
161+
To help with troubleshooting, gather the following logs and information:
162+
163+
- VML traces (for live migration):
164+
165+
```console
166+
VmlTrace.exe /m a /f all all
167+
VmlTrace.exe stop
168+
```
169+
170+
- NetSH network trace:
171+
172+
```console
173+
netsh trace start capture=yes tracefile=network-trace.etl overwrite=yes persistent=yes
174+
netsh trace stop
175+
```
176+
177+
- Integration services check:
178+
179+
```powershell
180+
Get-VMIntegrationService -VMName
181+
```
182+
183+
- CPU validation:
184+
185+
```console
186+
cat /proc/cpuinfo
187+
```
188+
189+
- Time settings (Linux):
190+
191+
```console
192+
timedatectl status
193+
timedatectl set-timezone
194+
```
195+
196+
## References
197+
198+
- [Supported CentOS and Red Hat Enterprise Linux virtual machines on Hyper-V](/windows-server/virtualization/hyper-v/supported-centos-and-red-hat-enterprise-linux-virtual-machines-on-hyper-v)
199+
- [Supported Debian virtual machines on Hyper-V](/windows-server/virtualization/hyper-v/supported-debian-virtual-machines-on-hyper-v)
200+
201+
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)