QEMU

From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.


QEMU (Quick EMUlator) is a generic, open-source hardware emulator and virtualization suite.

Introduction

QEMU is a virtual machine and runs on a host OS platform. Inside a virtual machine, QEMU can run a many operating system than its host. QEMU also can run an embedded system.

QEMU supports 32+ kinds of CPUs. QEMU emulates nearly all the opcodes of these CPUs.

QEMU has plugins. Accelerator is a type of plugin. Accelerator plugin allows execution directly by host CPU. When using an accelerator, QEMU executes CPU instructions the fastest.

QEMU is a Type-2 hypervisor that runs within user space and performs virtual hardware emulation.

  • Firstly, QEMU is a type 2 hypervisor.
  • QEMU can be paired with KVM to run VMs at near-native speed. This is accomplished by using hardware extensions such as: Intel VT-x or AMD-V.
  • It can then emulate user-level processes that allow applications compiled for one architecture to run on a different one.
  • Multiple operating modes: user-mode emulation, system emulation, KVM hosting, and Xen hosting,
  • QEMU can save and restore the state of VMs of all its running programs.
  • QEMU VMs can interface with many types of physical host hardware such as but not limited to CD-ROM drives, USB devices, audio interfaces, hard disks, and network cards.
  • Virtual disk image defaults to the `qcow2` format. The `qcow2` only uses as much host disk space as the guest OS grows to use. Using the snapshot method, guest OS can revert back to its desired state in time.
  • It does not depend on graphical output methods on the host system, instead making use of an integrated VNC server to access the screen of the guest OS.
  • QEMU on a host CPU can execute multiple virtual CPUs in parallel.


QEMU has support for acceleration plug-ins.

Available QEMU plugins are:

Virtualizer Accelerator Virtualization type Description Gentoo package name
qemu tcg full[1]/software-emulation QEMU's own Tiny Code Generator. This is the default. More frequently denoted as qemu and not qemu/tcg so often. app-emulation/qemu
qemu hvf[2] paravirtualization[3] Apple's Hypervisor.framework based on Intel VT.
qemu whpx[4] hybrid Microsoft's Windows Hypervisor Platform based on Intel VT or AMD-V.
qemu kvm paravirtualization[5] Linux Type-2 Hypervisor. This is the common choice for host using amd64, arm64, or mips[6]. Supports Microsoft Windows. app-emulation/qemu
qemu haxm[7] paravirtualization[8] Intel VT, by Intel Corporation.

QEMU, when used in conjunction with an accelerator, becomes a Type-1 hypervisor that runs in kernel space that allows a user space program access to the hardware virtualization features of various processors. Such an accelerator can be KVM (Kernel-based Virtual Machine) or Xen.

If no accelerator is used, QEMU will run entirely in user space using its built-in binary translator TCG (Tiny Code Generator). Using QEMU without an accelerator is relatively inefficient and slow.

Note
This article typically uses KVM as the accelerator of choice due to its GPL licensing and availability. Without KVM, nearly all commands described here will still work (unless KVM-specific).


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


Installation

BIOS and UEFI firmware

In order to utilize KVM either Vt-x (vmx) or AMD-V (svm) must be supported by the processor. Vt-x or AMD-V are Intel's and AMD's respective technologies for permitting multiple operating systems to concurrently execute operations on the processors.

To inspect hardware for virtualization support, issue the following command:

user $grep --color -E "vmx|svm" /proc/cpuinfo

For a period, manufacturers were shipping with virtualization turned off by default in the system's firmware. Note that toggling this feature in the firmware may actually require full removal of power from the system to take effect. If restarting the system does not work, try shutting down, unplugging the system, and pressing the power button in an unplugged state to discharge any residual energy from the power supply unit (PSU). Reapply power to the system to verify success.

If KVM support is available, there should be a "kvm" device listed at /dev/kvm. This will take effect after the system has booted to a KVM-enabled kernel.


Kernel

Described below are the basic requirements for KVM kernel configuration for the host OS. A more complete and up-to-date list can be found at the KVM Tuning Kernel page.

Note
Different guest (virtualized) OS may require additional kernel options. These are covered in the corresponding QEMU section pages.
KERNEL Enable high resolution timer support (CONFIG_HIGH_RES_TIMERS)
General setup  --->
    Timers subsystem  --->
        <*>   High Resolution Timer Support
Note
This includes support for ARM64 processors.
Physical CPU processor support - Host

If KVM support is not available, insert CONFIG_KVM=y into the /usr/src/linux/.config and rebuild/reinstall the kernel (and its initramfs image). Come back here after the host gets rebooted.


KERNEL Enable KVM Support (CONFIG_KVM)
[*] Virtualization  --->
    <*>   Kernel-based Virtual Machine (KVM) support
Note
This includes support for ARM64 processors.

Processor Support

KERNEL Enable KVM support for Intel processors (CONFIG_KVM_INTEL)
[*] Virtualization  --->
    <M>   KVM for Intel processors support
KERNEL Enable KVM support for AMD processors (CONFIG_KVM_AMD)
[*] Virtualization  --->
    <M>   KVM for AMD processors support
Warning
If both "KVM for Intel processors support" and "KVM for AMD processors support" are set as built into the kernel (*) an error message will appear from kprint from early boot. Since the system has only one type of processor (Intel or AMD), enabling one or both options as modules (M) will make the error message disappear.


Handling kernel config at CLI

To set the various kernel configuration settings from the command lines, the linux/scripts/kconfig/merge_config.sh shall be used here:

Mandatory kernel configuration options to set:

FILE /usr/src/kernel-kconfig-qemu-host.config
CONFIG_VIRTUALIZATION=y
CONFIG_KVM=y
CONFIG_KVM_INTEL=y
CONFIG_KVM_AMD=y
root #cd /usr/src/linux
root #scripts/kconfig/merge_config.sh .config /usr/src/kernel-kconfig-qemu-host.config

Useful kernel configuration options to use:

FILE /usr/src/kernel-kconfig-qemu-host-optional.config
CONFIG_VHOST_NET=y
CONFIG_HIGH_RES_TIMER=y
CONFIG_HPET=y
CONFIG_COMPACTION=y
CONFIG_MIGRATION=y
CONFIG_KSM=y
CONFIG_SYSFS=y
CONFIG_PROC_FS=y
CONFIG_TRANSPARENT_HUGEPAGE=y
CONFIG_CGROUPS=y
CONFIG_KVM_HYPERV=y
root #scripts/kconfig/merge_config.sh .config /usr/src/kernel-kconfig-qemu-host-optional.config


Tip
Recent Windows guests (at least Windows 10 22H2 and up) are required to set CONFIG_KVM_HYPERV (as per the optional configuration above).
If this is not selected, VMs will fail to provision (or boot) with errors like: failed to set MSR and Assertion `ret == cpu->kvm_msr_buf->nmsrs' failed.

Networking

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

KERNEL vhost-net kernel 5.7 and later (CONFIG_VHOST_NET)
Device Drivers  --->
    [*] VHOST drivers  --->
        <*> Host kernel accelerator for virtio net
KERNEL vhost-net (before kernel 5.7)
[*] Virtualization --->
    <*> Host kernel accelerator for virtio net
KERNEL Optional advanced networking support (CONFIG_NET_CORE, CONFIG_TUN)
Device Drivers  --->
    [*] Network device support  --->
        [*] Network core driver support
            <*> Universal TUN/TAP device driver support

Needed for 802.1d Ethernet bridging:

KERNEL Enabling 802.1d Ethernet Bridging support (CONFIG_IPV6, CONFIG_BRIDGE)
[*] Networking support  --->
        Networking options  --->
            <*> The IPv6 protocol
            <*> 802.1d Ethernet Bridging

Intel VT-g (integrated graphics adapter virtualization)

Mediated device passthrough for Intel GPUs (Broadwell to Comet Lake) [1].

KERNEL Intel VT-g (CONFIG_VFIO_MDEV, CONFIG_DRM_I915_GVT, CONFIG_DRM_I915_GVT_KVMGT)
Device Drivers  --->
        <*> VFIO Non-Privileged userspace driver framework
            <*> Mediated device driver framework
        Graphics Support  --->
            <*> Intel 8xx/9xx/G3x/G4x/HD Graphics
                [*] Enable Intel GVT-g graphics virtualization host support
            <*> Enable KVM host support Intel GVT-g graphics virtualization


USE flags

Some packages are aware of the qemu USE flag.

Review the possible USE flags for QEMU:

USE flags for app-emulation/qemu QEMU + Kernel-based Virtual Machine userland tools

+aio Enables support for Linux's Async IO
+curl Support ISOs / -cdrom directives via HTTP or HTTPS.
+doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
+fdt Enables firmware device tree support
+filecaps Use Linux file capabilities to control privilege rather than set*id (this is orthogonal to USE=caps which uses capabilities at runtime e.g. libcap)
+gnutls Enable TLS support for the VNC console server. For 1.4 and newer this also enables WebSocket support. For 2.0 through 2.3 also enables disk quorum support.
+jpeg Enable jpeg image support for the VNC console server
+oss Add support for OSS (Open Sound System)
+pin-upstream-blobs Pin the versions of BIOS firmware to the version included in the upstream release. This is needed to sanely support migration/suspend/resume/snapshotting/etc... of instances. When the blobs are different, random corruption/bugs/crashes/etc... may be observed.
+png Enable png image support for the VNC console server
+seccomp Enable seccomp (secure computing mode) to perform system call filtering at runtime to increase security of programs
+slirp Enable TCP/IP in hypervisor via net-libs/libslirp
+vhost-net Enable accelerated networking using vhost-net, see https://www.linux-kvm.org/page/VhostNet
+vnc Enable VNC (remote desktop viewer) support
accessibility Adds support for braille displays using brltty
alsa Enable alsa output for sound emulation
bpf Enable eBPF support for RSS implementation.
bzip2 Enable bzip2 compression support
capstone Enable disassembly support with dev-libs/capstone
debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
fuse Enables FUSE block device export
glusterfs Enables GlusterFS cluster fileystem via sys-cluster/glusterfs
gtk Add support for x11-libs/gtk+ (The GIMP Toolkit)
infiniband Enable Infiniband RDMA transport support
io-uring Enable the use of io_uring for efficient asynchronous IO and system requests
iscsi Enable direct iSCSI support via net-libs/libiscsi instead of indirectly via the Linux block layer that sys-block/open-iscsi does.
jack Add support for the JACK Audio Connection Kit
jemalloc Use dev-libs/jemalloc for memory management
keyutils Support Linux keyrings via sys-apps/keyutils
lzo Enable support for lzo compression
multipath Enable multipath persistent reservation passthrough via sys-fs/multipath-tools.
ncurses Enable the ncurses-based console
nfs Enable NFS support
nls Add Native Language Support (using gettext - GNU locale utilities)
numa Enable NUMA support
opengl Add support for OpenGL (3D graphics)
pam Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip
pipewire Enable pipewire output for sound emulation
plugins Enable qemu plugin API via shared library loading.
pulseaudio Enable pulseaudio output for sound emulation
python Add optional support/bindings for the Python language
rbd Enable rados block device backend support, see https://docs.ceph.com/en/mimic/rbd/qemu-rbd/
sasl Add support for the Simple Authentication and Security Layer
sdl Enable the SDL-based console
sdl-image SDL Image support for icons
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
smartcard Enable smartcard support
snappy Enable support for Snappy compression (as implemented in app-arch/snappy)
spice Enable Spice protocol support via app-emulation/spice
ssh Enable SSH based block device support via net-libs/libssh2
static Build the User and Software MMU (system) targets as well as tools as static binaries
static-user Build the User targets as static binaries
systemtap Enable SystemTap/DTrace tracing
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
udev Enable virtual/udev integration (device discovery, power and storage device support, etc)
usb Enable USB passthrough via dev-libs/libusb
usbredir Use sys-apps/usbredir to redirect USB devices to another machine over TCP
vde Enable VDE-based networking
virgl Enable experimental Virgil 3d (virtual software GPU)
virtfs Enable VirtFS via virtio-9p-pci / fsdev. See https://wiki.qemu.org/Documentation/9psetup
vte Enable terminal support (x11-libs/vte) in the GTK+ interface
xattr Add support for getting and setting POSIX extended attributes, through sys-apps/attr. Requisite for the virtfs backend.
xdp Enable support for XDP through net-libs/xdp-tools
xen Enables support for Xen backends
zstd Enable support for ZSTD compression
Data provided by the Gentoo Package Database · Last update: 2025-04-05 17:17 More information about USE flags

Note
More than one USE flag (gtk, ncurses, sdl, or spice) can be enabled for graphical output. If graphics are desired, it is generally recommended to enable more than one graphical USE flag.
Note
If virt-manager is going to be used, be sure to enable the usbredir and spice USE flags on the qemu package for correct operation.

USE_EXPAND

Additional ebuild configuration frobs 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 shockingly ambitious) purpose of these targets is to "magically" allow importing user-space linux ELF binaries from a different architecture into the native system (like multilib, without the awkward need for a software stack or CPU capable of running it).

In order to enable QEMU_USER_TARGETS and QEMU_SOFTMMU_TARGETS we can edit the variables globally in /etc/portage/make.conf, i.e.:

FILE /etc/portage/make.conf
QEMU_SOFTMMU_TARGETS="arm x86_64 sparc"
QEMU_USER_TARGETS="x86_64"


Or, the /etc/portage/package.use file(s) can be modified. Two equivalent syntaxes are available: traditional USE flag syntax, i.e.:

FILE /etc/portage/package.use
app-emulation/qemu qemu_softmmu_targets_arm qemu_softmmu_targets_x86_64 qemu_softmmu_targets_sparc
app-emulation/qemu qemu_user_targets_x86_64


Another alternative is to use the newer USE_EXPAND-specific syntax:

FILE /etc/portage/package.use
app-emulation/qemu QEMU_SOFTMMU_TARGETS: arm x86_64 sparc QEMU_USER_TARGETS: x86_64


Emerge

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

root #emerge --ask app-emulation/qemu


Configuration

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

  • Usage options - Contains common configuration options used with QEMU (graphics/display, networking, RAM, storage, processor, etc).
  • 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
  • OS2WarpV3 guest - Describes the configuration steps needed to setup a virtualized OS2WarpVs=3 guest with QEMU.

Environment variables

  • G_MESSAGES_DEBUG
  • LISTEN_FDS
  • LISTEN_PID
  • QEMU_AUDIO_DRV
  • QEMU_MODULE_DIR
  • XDG_RUNTIME_DIR

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

User name qemu is required, defined by acct-user/qemu and evoked by sys-emulator/qemu package.

Group name qemu is required, defined by acct-group/qemu and evoked by sys-emulator/qemu package.


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


Usage

QEMU can be used in two ways, with GUI front ends and through the command line. The configuration of QEMU depends on which method is employed:

  • GUI (Front-End) - To make life easier, there are multiple user-friendly front ends to QEMU: See Front-ends
  • CLI

Invocation

QEMU supports around 34 different CPU architectures. To find the desired architecture, list what is installed.

user $ls /usr/bin/qemu-system-*
user $qemu-system-x86_64 -help

Permissions

In order to run a KVM-accelerated virtual machine without logging in as root, add normal users to the kvm group. Replace <username> in the example command below with the appropriate user(s):

root #gpasswd -a larry kvm


Creation of a disk image

To create a raw disk image with 4 GiB size:

user $qemu-img create -f raw "/home/larry/my-systems-disk-image.img" 4G
Formatting 'my-systems-disk-image.img', fmt=raw size=4294967296
user $ls -lh
total 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img

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

user $qemu-img create -f raw "/home/larry/my-systems-disk-image.img" -o nocow=on 4G
Formatting 'my-systems-disk-image.img', fmt=raw size=4294967296 nocow=on
user $ls -lh
total 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img

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

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

user $qemu-img create -f qcow2 "/home/larry/my-systems-disk-image.qcow2" 4G
Formatting 'my-systems-disk-image.qcow2', fmt=qcow2 cluster_size=65536 extended_l2=off compression_type=zlib size=4294967296 lazy_refcounts=off refcount_bits=16
user $ls -l
total 196K
-rw-r--r-- 1 larry larry 193K Apr 12 11:30 my-systems-disk-image.qcow2


Preparation of a bootable disk image from scratch

A system can be copied onto a disk image, when not using a cdrom 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:

root #losetup --find --partscan --show "/home/larry/qemu/my-systems-disk-image.img"
/dev/loop0
  • The parameter --find finds the first unused loop device.
  • The parameter --partscan forces the 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 follwing command:

root #losetup --list
NAME       SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE                                  DIO LOG-SEC
/dev/loop0         0      0         0  0 /home/larry/qemu/my-systems-disk-image.img   0     512

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

Print the partition table:

root #parted "/dev/loop0" "unit mib print"

Create a new partition table (msdos disk label):

Warning
Make absolutely sure to select the correct loop device, since this may overwrite an existing partition table; resulting in data loss, if the overwritten partition table cannot be recovered.
root #parted "/dev/loop0" "mklabel msdos"
Information: You may need to update /etc/fstab.

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:

root #parted "/dev/loop0" "unit mib print"

Create an ext4 partition with an offset of 2 MiB:

root #parted "/dev/loop0" "mkpart primary ext4 2MiB -1"

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

The first partition has been successfully created:

root #parted "/dev/loop0" "unit mib print"

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

root #ls -l "/dev/loop0"*
brw-rw---- 1 root disk   7, 0 Apr 12 12:33 /dev/loop0
brw-rw---- 1 root disk 259, 0 Apr 12 12:33 /dev/loop0p1

Set the boot flag:

root #parted "/dev/loop0" set 1 boot on

All partition flags can be found in the column Flags:

root #parted "/dev/loop0" "unit mib print"

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

root #mkfs.ext4 "/dev/loop0p1"

Mount it at /mnt/:

root #mount "/dev/loop0p1" "/mnt/"
root #df --human-readable --print-type "/mnt/"
Filesystem     Type  Size  Used Avail Use% Mounted on
/dev/loop0p1   ext4  3.9G   24K  3.7G   1% /mnt

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

root #mkdir --parents --verbose "/mnt/boot/grub"
mkdir: created directory '/mnt/boot'
mkdir: created directory '/mnt/boot/grub'

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

root #grub-install --boot-directory="/mnt/boot/grub" "/dev/loop0"

Unmount the filesystem and detach the loop device:

root #umount "/mnt/"
root #losetup --detach "/dev/loop0"

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:

root #losetup --list
NAME       SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE                                  DIO LOG-SEC
/dev/loop0         0      0         0  0 /home/larry/qemu/my-systems-disk-image.img   0     512
root #lsof | grep "/mnt"
sleep     31813                       root cwd       DIR              259,0      4096              131074 /mnt/boot/grub
root #kill -SIGTERM 31813

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) or tcg (Tiny Code Generator) or Xen(wikip[2]).

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

To get a list of CPUs:

user $qemu-system-x86_64 -cpu help

Show the available accelerators:

user $qemu-system-x86_64 -accel help


Starting QEMU

This is how to start a virtual machine with the same feature set as the host cpu, a raw disk image and 2G of ram. By default a vnc server is started that runs with no password protection and listens on the loop interface. QEMU is advised to listen on a local UNIX socket with the following command. Set the file permissions appropriately to protect the VNC server from unauthorized access. A cdrom installation and boot medium is added with "-cdrom filename.img"

user $qemu-system-x86_64 -vnc unix:/home/user/.qemu-vnc-socket -cpu host -drive file=/var/virt/rootfs-build-tc,format=raw -m 2G
Warning
Starting the server with -vnc :0 it listens on port 5900 (first display) on all interfaces with no password protection.


Troubleshooting

"kvm: already loaded the other module"

Sometimes during the early boot splash, the error message "kvm: already loaded the other module" can be seen. This message indicates 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. For example, if the system has an Intel processor, enable the Intel KVM, and then make sure the AMD KVM is set as a module (M) or is disabled (N). The relevant options to enable or disable can be found in the kernel's .config file via the CONFIG_KVM_INTEL and CONFIG_KVM_AMD variables or in the configuration section 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 driver:

root #modprobe tun

If that works, add this to a file in /etc/modules-load.d/ to load on startup:

FILE /etc/modules-load.d/qemu-modules.conf
tun

Configuration does not support video model 'qxl'

This is usually the case if QEMU is not built with 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:

FILE /etc/portage/package.use/qemu
app-emulation/qemu spice

Then rebuild the package:

root #emerge --ask app-emulation/qemu

My qemu has kvm support on some guest architectures

KVM works only for the same 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:

CODE SELinux error from virt-manager
Error starting domain: unable to set socket security context 'system_u:system_r:svirt_t:s0:c123,c456': Invalid argument
CODE SELinux error from the kernel
kernel: SELinux:  Context system_u:object_r:svirt_image_t:s0:c123,c456 is not valid (left unmapped).

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:

CODE Libvirt domain XML with manually specified seclabel fields
<domain type="kvm">
  <name>fedora</name>
  ...
  <devices>
    <disk type="file" device="disk">
      <driver name="qemu" type="qcow2"/>
      <source file="/var/lib/libvirt/images/fedora.qcow2">
        <seclabel model='selinux' relabel='yes'>
          <label>system_u:object_r:svirt_image_t</label>
        </seclabel>
      </source>
      <target dev="vda" bus="virtio"/>
      <address type="pci" domain="0x0000" bus="0x04" slot="0x00" function="0x0"/>
    </disk>
  ...
  <seclabel type='static' model='selinux' relabel='yes'>
    <label>system_u:system_r:svirt_t</label>
  </seclabel>
</domain>

Static-user and LTO

GCC will use a huge amount of RAM when LTO is enabled on the system if any of the ppc64 options are enabled while using the static-user 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 used to compile zlib and glib to the one being used to compile qemu, this can be fixed by rebuilding both before compiling qemu again.

root #emerge --ask sys-libs/zlib dev-libs/glib

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

For optimal performance, it is recommended that modern Windows guests be run under a kernel with CONFIG_KVM_HYPERV enabled. As an additional benefit, if this option is not enabled, on some hardware, VMs will fail to provision, to boot, or present with a BSOD.

The technical reasons for this are as follows: later versions of Windows, when running as virtual machines, sometimes attempt to access hardware registers (specifically, Model Specific Registers or MSRs) 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 BSOD and halting the virtual machine.

Tip
unhandled rdmsr or unhandled wrmsr messages in the system logs of the host indicate attempts to access undefined MSRs. Failures may also be more obvious, like failed to set MSR and Assertion `ret == cpu->kvm_msr_buf->nmsrs' failed from qemu-system-*.

An alternative is passing the option kvm.ignore_msrs=1 on the kernel command line or as an option to the KVM module:

FILE /etc/modprobe.d/kvm.conf
options kvm ignore_msrs=1

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

Tip
While ignore_msrs can be a quick fix for BSODs related to MSR access (not all BSODs are!), it is likely that this can be addressed properly by enabling the appropriate kernel option, as documented above.

This option should only need to be set if there are still undefined MSRs (and if there are it's probably a bug that needs to be reported to the software vendor or KVM/QEMU upstream).


Removal

There may be image files left behind after the removal of the QEMU package.

Unmerge

root #emerge --ask --depclean --verbose app-emulation/qemu


See also


External resources

References

  1. ↑ https://en.wikipedia.org/wiki/Full_virtualization
  2. ↑ https://developer.apple.com/documentation/hypervisor
  3. ↑ https://en.wikipedia.org/wiki/Paravirtualization
  4. ↑ https://github.com/RceNinja/notes/blob/master/notes/build_qemu_with_enabled_hyper-v_acceleration_(whpx)_on_windows.md
  5. ↑ https://en.wikipedia.org/wiki/Paravirtualization
  6. ↑ QEMU / KVM CPU model configuration
  7. ↑ https://github.com/intel/haxm
  8. ↑ https://en.wikipedia.org/wiki/Paravirtualization
  9. ↑ https://www.qemu.org/docs/master/system/qemu-block-drivers.html#cmdoption-qcow2-arg-nocow
Retrieved from "https://wiki.gentoo.org/index.php?title=QEMU&oldid=1370725"