QEMU

• English
• français
• magyar
• 中文(中国大陆)‎

General setup --->
 Timers subsystem --->
 <*> High Resolution Timer Support

[*] Virtualization --->
 <*> Kernel-based Virtual Machine (KVM) support

[*] Virtualization --->
 <M> KVM for Intel processors support

[*] Virtualization --->
 <M> KVM for AMD processors support

CONFIG_VIRTUALIZATION=y
CONFIG_KVM=y
CONFIG_KVM_INTEL=y
CONFIG_KVM_AMD=y

Accelerated networking, required for vhost-net USE flag (recommend):

Needed for 802.1d Ethernet bridging:

Intel VT-g (integrated graphics adapter virtualization)

Mediated device passthrough for Intel GPUs (Broadwell to Comet Lake)^[4]

USE flags

Some packages are aware of the qemu USE flag.

Review the possible USE flags for QEMU:

USE_EXPAND

Additional ebuild configuration are provided as the USE_EXPAND variables QEMU_USER_TARGETS and QEMU_SOFTMMU_TARGETS. See app-emulation/qemu for a list of all the available targets (there are many; most are very obscure and may be ignored; leaving these variables at their default values will disable almost everything, which is probably just fine for most users).

For each target specified, a qemu executable will be built. A softmmu target is the standard qemu use-case of emulating an entire system (like VirtualBox or VMWare, but with optional support for emulating CPU hardware along with peripherals). user targets execute user-mode code only; the (somewhat ambitious) purpose of these targets, is to "magically" allow importing user namespace Linux ELF binaries from a different architecture into the native system (like multilib, without the need for a software stack or CPU capable of running it).

In order to enable QEMU_USER_TARGETS and QEMU_SOFTMMU_TARGETS, use /etc/portage/package.use :

Emerge

After reviewing and adding any desired USE flags, emerge app-emulation/qemu :

Configuration

The following sub-articles provide detailed instructions on QEMU configurations and options:

• QEMU/Options — describes some of the options useful for configuring QEMU virtual machines.
• QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.
• QEMU/Windows guest — setup of a Windows guest using QEMU
• QEMU/OS2WarpV3 guest

Environment variables

Files

Files that QEMU uses.

Single File

• /etc/libvirt/qemu.conf - QEMU configuration file.
• /etc/libvirt/qemu-lockd.conf - QEMU lock files
• /etc/libvirt/qemu-sanlock.conf - QEMU SAN lock
• /etc/libvirt/qemu/<domain-name>.xml - Domain XML setting for a virtual machine or container.
• /etc/libvirt/qemu/autostart/<domain-name>.xml - Autostart this domain (virtual machine or container).
• /etc/libvirt/qemu/networks/<network-name>.xml - Network XML setting file for a network connection
• /etc/libvirt/qemu/networks/autostart/<network-name>.xml - Autostart this network connection.
• /var/lib/libvirt/qemu/channel/target/<domain-name>/<socket-file> - UNIX socket file for Libvertd daemon API
• /var/cache/libvirt/qemu/capabilities/<hash-value>.xml - Host OS capabilities in XML format
• /var/lib/libvirt/qemu/checkpoint/
• /var/lib/libvirt/qemu/<domain-9-XXXX>/ - holds UNIX sockets and AES keys for this domain.
• /var/lib/libvirt/qemu/dump/
• /var/lib/libvirt/qemu/nvram/
• /var/lib/libvirt/qemu/ram/
• /var/lib/libvirt/qemu/save/ - holding directory of hibernation images
• /var/lib/libvirt/qemu/snapshot/ - holding directory of snapshots
• /var/run/libvirt/qemu - various UNIX socket and PID files for the libvirtd daemon.

Image File

QEMU supports the following disk image formats:

• QEMU copy-on-write (.qcow2, .qed, .qcow, .cow)
• VirtualBox Virtual Disk Image (.vdi)
• CD/DVD (ISO-9660) images (.iso)
• Raw images (.img), that guest OS can control
• VFAT-16
• VMware Virtual Machine Disk (.vmdk)
• Virtual PC Virtual Hard Disk (.vhd)
• Parallels disk image (.hdd, .hds) – Read-only
• Apple macos Universal Disk Image Format (.dmg) – Read-only
• Bochs – Read-only
• Linux cloop – Read-only

Additional software

To connect to the SPICE server of QEMU, a GUI client like net-misc/spice-gtk is required.

Usage

QEMU can be used with GUI front-ends or via the command line. There are multiple user-friendly front ends to QEMU: See Front-ends.

Invocation

QEMU supports around 34 different CPU architectures. To find the desired architecture, one can list them like so:

Permissions

In order to run a KVM-accelerated virtual machine without root privileges, one can add normal users to the kvm group:

Creation of a disk image

To create a raw disk image with 4 GiB size:

To create a raw disk image with copy-on-write disabled:

The option nocow is also a file attribute, which can be determined via the command lsattr^[5] .

The following will create a qcow2 disk image (useful, if the host filesystem does not support sparse files):

Preparation of a bootable disk image from scratch

A system can be copied onto a disk image, when not using a CD-ROM installation medium.

By default, qemu uses a bios-firmware to boot the system.

The disk can be prepared with a msdos disk label and a gap between the end of the 512-byte-MBR (Master Boot Record) and the start of the first partition. The gap is needed for boot loaders like GRUB, which place boot-code within this gap.

The following example uses the raw disk image, which was created above.

A raw disk image can be prepared by attaching it as a loop device:

• The parameter --find finds the first unused loop device.
• The parameter --partscan forces the Linux kernel to scan the partition table on the newly created loop device, where the default sector size of 512 bytes is assumed.
• The parameter --show displays the name of the assigned loop device, if the parameter --find is used.

Attached loop devices can be listed with the following command:

Then, the loop device can be formatted like a normal disk.

Print the partition table:

Create a new partition table (msdos disk label):

The returned information can be ignored, since an entry in the configuration file /etc/fstab is not needed.

parted now indicates, that the partition table}} is msdos:

Create an ext4 partition with an offset of 2 MiB:

The parameter -1 represents the last sector of the partition.

The first partition has been successfully created:

This will also attach a new loop device at /dev/loop0p1:

Set the boot flag:

All partition flags can be found in the column "Flags":

Create the ext4 filesystem, which was declared via parted earlier:

Mount it at /mnt:

Create the directories /mnt/boot/grub, which will be used by GRUB later:

Install GRUB boot loader on the loop device and advice it to install its files to /mnt/boot/grub/:

Unmount the filesystem and detach the loop device:

If the loop device is still busy - for example, processes are still accessing /mnt/ - no error will be returned. This can be verified and solved with the following commands:

This is sufficient to boot into a grub2 boot prompt. This is can be used as the basis for a bootable system.

CPU selection

QEMU CPU selections have additional support for accelerators, like kvm (Kernel Virtual Machine), tcg (Tiny Code Generator) or Xen.

The accelerator can usually only accelerate the features, which are available on the host CPU. So the selection of the CPU affects the performance.

To get a list of CPUs, one can use the parameters -cpu help.

To show available accelerators, one can use the parameters -accel help.

Starting QEMU

The following explains, how to start a virtual machine with the same feature set as the host CPU, a raw disk image and 2 GB of RAM.

By default, a VNC server starts without password protection and listens on the loop interface. QEMU is advised to listen on a local UNIX socket with the following command:

Connecting to the virtual machine via VNC

In order to connect to the VNC server, the command vncviewer, which comes from the package net-misc/tigervnc , can be used:

This will open a separate window, where one gets greeted with a GRUB shell, which was installed via grub-install earlier:

Qemu minimal vm with grub2.png

Troubleshooting

qemu-system-x86_64: CPU model 'host' requires KVM or HVF

When trying to start a virtual machine, using the parameter -cpu host, one may encounter the following error:

In order to fix this, use the parameter -enable-kvm, which will enable KVM full virtualization support:

kvm: already loaded the other module

Sometimes, during the early boot splash, the following error message may be seen:

This indicates, that both, the Intel and the AMD kernel virtual machine settings, have been enabled in the kernel. To fix this, enable it as a module or disable either the Intel or AMD KVM option specific to the system's processor in the kernel configuration as described above.

Creating TUN/TAP device - No such file or directory

Sometimes, this error can occur, if TUN/TAP support cannot be found in the kernel. To solve this, try loading the tun kernel module:

If this works, add tun to a file in /etc/modules-load.d/, so the kernel module will be loaded on every boot of the host system:

Configuration does not support video model 'qxl'

This is usually the case, if QEMU is built without the spice USE flag. To resolve this issue, try to build QEMU with the correct USE flag.

First add spice to via a package.use file:

Then recompile the QEMU:

QEMU has kvm support on some guest CPU architectures

KVM only works for the same CPU architecture. An ARM64 host cannot handle x86_64 instructions.

Invalid context errors on SELinux systems

By default, libvirt generates a random SELinux MCS label for the QEMU process, when it is started. If the loaded SELinux policy does not support MCS categories, the resulting security context will be invalid:

The solution is, either to switch to one of the policy types, which supports MCS categories or manually set the virtual machine's security labels, without MCS categories:

Static-user and LTO

GCC will use a huge amount of RAM, if LTO is enabled on the system, if any of the ppc64 options are enabled, while using the static-user USE flag. Because of this, it is recommended to disable LTO, while compiling in this configuration or use Clang if LTO is required. See bug #883419

lto1: internal compiler error: original not compressed with zstd

This is caused by a mismatch of GCC, where qemu is compiled against sys-libs/zlib and dev-libs/glib . This can be fixed, by recompiling both libraries, before recompiling app-emulation/qemu again:

Windows guests fail to provision, boot or Blue Screen of Death (BSOD) on startup

For optimal performance, it is recommended, that modern Windows guests (at least Windows 10 22H2 and up) run under a kernel with CONFIG_KVM_HYPERV enabled. If this Kernel driver is not enabled, VMs will fail to provision, to boot or run into a Blue Screen.

Later versions of Windows, if running as virtual machines, sometimes attempt to access hardware registers - specifically MSRs (Model Specific Registers) - that are not actually defined for the emulated processor within the virtual environment. This is often, due to how Windows interacts with hardware, a driver trying to be overly clever or even bugs within the operating system itself. While these MSR accesses might be valid on physical processors, the virtualized environment presented by KVM may not support them.

KVM's default behavior is to attempt to emulate these MSR accesses, but when encountering an undefined register, it reports an invalid instruction error to the virtual Windows instance. This error is often fatal, resulting in a Blue Screen and halting the virtual machine.

An alternative is passing the kernel parameter kvm.ignore_msrs=1 on the kernel command line or as a parameter to the kvm module:

The ignore_msrs parameter instructs KVM to ignore any attempts by the virtual Windows machine to access these undefined MSRs. Instead of generating an error and causing a Blue Screen, KVM silently bypasses the problematic instruction. This allows Windows to continue running, albeit potentially with some minor performance implications or masked underlying issues.

Removal

Unmerge

See also

• Comparison of virtual machines — compares the features of several platform virtual machines.
• Fast Virtio VM — explains a way to build a blazing fast Gentoo VM under KVM using Virtio and mdev.
• GPU passthrough with virt-manager, QEMU, and KVM — directly present an internal PCI GPU as-is for direct use by a virtual machine
• QEMU with Open vSwitch network
• Virtualization — the concept and technique that permits running software in an environment separate from a computer operating system.
• QEMU/Front-ends — facilitate VM management and use
• Libvirt — a virtualization management toolkit
• Libvirt/QEMU_networking — details the setup of Gentoo networking by Libvirt for use by guest containers and QEMU-based virtual machines.
• Libvirt/QEMU_guest — creation of a guest domain (virtual machine, VM), running inside a QEMU hypervisor, using tools found in libvirt package.
• Virt-manager — lightweight GUI application designed for managing virtual machines and containers via the libvirt API.
• Virt-manager/QEMU_guest — creation of a guest virtual machine (VM) running inside a QEMU hypervisor using just the virt-manager GUI tool.
• QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.
• QEMU/Bridge with Wifi Routing
• Category:QEMU Guests
• Remote_desktop — a guide to remote desktop software on Gentoo

External resources

• https://www.linux-kvm.org/page/KvmOnGentoo - The Gentoo article on the KVM wiki
• https://wiki.qemu.org/Main_Page - The Official QEMU wiki

References