Skip to content

KVM: default x86 guests to vga video model when none is configured - #13807

Open
andrijapanicsb wants to merge 1 commit into
apache:mainfrom
andrijapanicsb:kvm-x86-vga-default
Open

KVM: default x86 guests to vga video model when none is configured#13807
andrijapanicsb wants to merge 1 commit into
apache:mainfrom
andrijapanicsb:kvm-x86-vga-default

Conversation

@andrijapanicsb

@andrijapanicsb andrijapanicsb commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Fixes #13806

Description

On KVM, CloudStack emits no <video> element unless the agent property
vm.video.hardware or the VM setting video.hardware is set. libvirt then defaults
x86 guests to cirrus, which has been deprecated in QEMU for years (EL9 qemu-kvm
already prints a deprecation warning) and renders a completely blank console on
Windows Server 2025 Core
— input and qemu-guest-agent keep working, but the display
shows nothing. Verified A/B on the same VM: cirrus = blank LogonUI, vga = renders
correctly (details and repro in #13806).

With this PR, when no video model is explicitly configured (no agent property, no VM
detail), the KVM agent emits <model type='vga' vram='32768'/> (32 MiB) for x86
guests. Precedence is unchanged: VM detail video.hardware/video.ram > agent
property vm.video.hardware/vm.video.ram > this default. The new default takes
effect on the next VM stop/start; running VMs are not modified.

Why only x86 — why not aarch64/s390x as well?

Both halves of the argument flip on non-x86 architectures:

  1. The bug cannot happen there. The cirrus injection this PR fixes is libvirt's
    x86-specific legacy default. On aarch64 virt machines there is no cirrus at all —
    libvirt/QEMU pick appropriate devices, so unconfigured aarch64 guests are not
    broken today. Same for s390x (virtio-gpu-ccw).
  2. vga is the wrong device there. Std VGA is legacy x86 hardware — VGA I/O
    ports, VGA BIOS text mode. The aarch64 virt machine has no legacy I/O, so VGA can
    only be exposed as a bare PCIe framebuffer; guest support for that is spotty
    (edk2 can drive it, guest kernels vary, and Windows-on-ARM has no std VGA driver at
    all). The native display devices on aarch64 are virtio-gpu and ramfb.

Unconditionally injecting <model type='vga'/> on non-x86 would therefore change
behavior where nothing is broken, possibly to a device the guest cannot drive — the
opposite of what this PR does on x86. If aarch64 display defaults ever need
attention, the right fix is a separate virtio-gpu/ramfb default. The arch check
follows the existing pattern in LibvirtComputingResource: the guest.cpu.arch
agent property first, the VM's arch as fallback, null treated as x86 (same assumption
createGuestFromSpec makes).

Is there any x86 guest OS still potentially in use today that fails on vga?

We could not identify a single one. QEMU itself switched its own default video
adapter from cirrus to std VGA back in QEMU 2.2 (December 2014), so every plain QEMU
invocation for the last decade has used it. In particular:

  • CentOS 5 / Ubuntu 12.04 (oldest Linux realistically still around): text console
    is plain VGA text mode; X falls back to the vesa driver, which drives std VGA's
    VBE modes fine.
  • Windows Server 2003: ships a standard VGA/VBE-capable driver; works.
  • Windows Server 2008 and newer: Microsoft removed the cirrus driver entirely
    after the XP/2003 era, so on cirrus these guests already run the Basic Display
    driver in dumb-VGA mode — cirrus offers them nothing over std VGA, and per this
    report is now actively worse.
  • Museum pieces (Windows 3.x/9x/NT4, OS/2): the only class that loses anything —
    they had accelerated cirrus drivers and drop to unaccelerated 640x480 on std VGA.
    They still boot and still display.

So the risk of this default change is next to zero, though functional testing with a
couple of different guest OSes is of course advised. On the flip side, staying on
cirrus is a time bomb: it is deprecated in QEMU, EL9 warns about it, and once EL10/11
builds drop the device, every unconfigured guest would fail outright.

Types of changes

  • Bugfix

Feature/Enhancement Scale or Bugfix Severity

  • Severity: Major (blank console on Windows Server 2025 Core guests)

How Has This Been Tested?

  • New unit tests in LibvirtComputingResourceTest:
    • x86 guest (Linux os type), nothing configured → vga/32768
    • x86 guest (Windows os type), nothing configured → vga/32768
    • Explicit VM detail → detail wins
    • Agent property set → property wins
    • aarch64 guest, nothing configured → no <video> element (unchanged)
  • Lab (EL9 KVM host, no vm.video.hardware set): restarting a VM without a
    video.hardware detail now produces <model type='vga' vram='32768'/> in
    virsh dumpxml; Windows Server 2025 Core console renders correctly instead of
    staying blank.

Without an explicit video model (vm.video.hardware agent property or
video.hardware VM detail), CloudStack emits no <video> element and libvirt
defaults x86 guests to cirrus, which is deprecated in QEMU and renders a
blank console on Windows Server 2025 Core guests. Default unconfigured x86
guests to vga with 32 MiB of VRAM instead. Explicit VM details and agent
properties keep precedence; non-x86 guests (aarch64, s390x) are unchanged.

Fixes apache#13806
@codecov

codecov Bot commented Aug 5, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 75.00000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 19.65%. Comparing base (4f11707) to head (59f286c).

Files with missing lines Patch % Lines
...ervisor/kvm/resource/LibvirtComputingResource.java 75.00% 0 Missing and 2 partials ⚠️
Additional details and impacted files
@@            Coverage Diff            @@
##               main   #13807   +/-   ##
=========================================
  Coverage     19.65%   19.65%           
- Complexity    19792    19795    +3     
=========================================
  Files          6368     6368           
  Lines        574881   574889    +8     
  Branches      70351    70354    +3     
=========================================
+ Hits         112970   112972    +2     
- Misses       449639   449647    +8     
+ Partials      12272    12270    -2     
Flag Coverage Δ
uitests 3.41% <ø> (ø)
unittests 20.92% <75.00%> (+<0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@andrijapanicsb

Copy link
Copy Markdown
Contributor Author

My good friend.... @blueorangutan package kvm

@blueorangutan

Copy link
Copy Markdown

@andrijapanicsb a [SL] Jenkins job has been kicked to build packages. It will be bundled with kvm SystemVM template(s). I'll keep you posted as I make progress.

@blueorangutan

Copy link
Copy Markdown

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 18778

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

KVM: default (libvirt-chosen) cirrus video renders a blank console for Windows Server 2025 Core — default should be vga

2 participants