QEMU

This page contains changes which are not marked for translation.

Resources

Home

Wikipedia

QEMU (Quick EMUlator) is a generic, open source hardware emulator and virtualization suite. Often it is used in conjunction with acceleration in the form of a Type-I hypervisor such as 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:

QEMU/Bridge with Wifi Routing
QEMU/KVM_IPv6_Support - IPv6 support in QEMU/KVM.
Linux guest - Describes the configuration steps needed to setup a virtualized Linux guest with QEMU.
Virtiofs - Describes using virtiofsd to share a directory between the host and a Linux guest.
Usage options - Contains common configuration options used with QEMU (graphics/display, networking, RAM, storage, processor, etc).
OS2WarpV3 guest - Describes the configuration steps needed to setup a virtualized OS2WarpVs=3 guest with QEMU.
Windows guest - Describes the configuration steps needed to setup a virtualized Windows guest with QEMU.

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 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. 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 #Usage section pages.

KERNEL Enable high resolution timer support (CONFIG_HIGH_RES_TIMERS)

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

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 processor (Intel or AMD) enabling one or both options as modules (M) will make the error message disappear.

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 and newer) [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

`accessibility`	Adds support for braille displays using brltty
`aio`	Enables support for Linux's Async IO
`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
`curl`	Support ISOs / -cdrom directives via HTTP or HTTPS.
`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
`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)
`fuse`	Enables FUSE block device export
`glusterfs`	Enables GlusterFS cluster fileystem via sys-cluster/glusterfs
`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.
`gtk`	Add support for x11-libs/gtk+ (The GIMP Toolkit)
`infiniband`	Enable Infiniband RDMA transport support
`io-uring`	Enable efficient I/O via sys-libs/liburing.
`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`	Enable jemalloc allocator support
`jpeg`	Enable jpeg image support for the VNC console server
`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)
`oss`	Add support for OSS (Open Sound System)
`pam`	Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip
`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.
`pipewire`	Enable pipewire output for sound emulation
`plugins`	Enable qemu plugin API via shared library loading.
`png`	Enable png image support for the VNC console server
`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
`seccomp`	Enable seccomp (secure computing mode) to perform system call filtering at runtime to increase security of programs
`selinux`	!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
`slirp`	Enable TCP/IP in hypervisor via net-libs/libslirp
`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
`vhost-net`	Enable accelerated networking using vhost-net, see https://www.linux-kvm.org/page/VhostNet
`virgl`	Enable experimental Virgil 3d (virtual software GPU)
`virtfs`	Enable VirtFS via virtio-9p-pci / fsdev. See https://wiki.qemu.org/Documentation/9psetup
`vnc`	Enable VNC (remote desktop viewer) support
`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.
`xen`	Enables support for Xen backends
`zstd`	Enable support for ZSTD compression

Data provided by the Gentoo Package Database · Last update: 2024-03-23 08:35 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 a heck of a lot of them; most of them 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 (that is, they are 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

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.

Front ends

To make life easier, there are multiple user-friendly front ends to QEMU:

Name	Package	Homepage	Description
AQEMU		https://anyon3.github.io/aqemu.html	Graphical interface for QEMU and KVM emulators, using Qt5.
Boxes	gnome-extra/gnome-boxes	https://wiki.gnome.org/Apps/Boxes	GNOME App to manage virtual and remote machines.
libvirt	app-emulation/libvirt	https://www.libvirt.org/	C toolkit to manipulate virtual machines.
QtEmu		https://gitlab.com/qtemu/gui	Qt-based front-end for QEMU.
qt-virt-manager		https://f1ash.github.io/qt-virt-manager/	A graphical user interface for libvirt written in Qt5.
virt-manager	app-emulation/virt-manager	https://virt-manager.org	A graphical tool for administering virtual machines.

Command line

QEMU binaries are used to run the virtualized guest.

user $qemu-system-x86_64 [options] [disk_image]

Permissions

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

root #gpasswd -a <username> kvm

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 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, 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 huge amount of RAM when LTO is enabled on the system while using the static-user flag, because of this 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

BSOD when booting Windows 10

Create this file:

FILE /etc/modprobe.d/kvm.conf

options kvm ignore_msrs=1

and restart the system.

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