QEMU/uz
QEMU (Quick EMUlator) is a generic, open-source hardware emulator and virtualization suite.
Introduction
QEMU is a hardware emulator and virtualization tool, which runs on a host OS platforms. Inside a virtual machine, QEMU can emulate multiple operating systems; it can also emulate embedded systems.
QEMU supports 32+ kinds of CPUs. It emulates nearly all the opcodes of these CPUs.
QEMU has several plugins: Accelerator is one of them. This plugin allows execution directly by the host CPU. When using an accelerator, QEMU executes CPU instructions the fastest.
QEMU is a Type-2 hypervisor, which runs within user namespace and performs virtual hardware emulation.
- 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, which allow applications, compiled for one architecture, to run on a different one.
- There are multiple operating modes: user-mode emulation, system emulation, KVM hosting and Xen hosting.
- QEMU can save and restore the state of virtual machines of all its running programs.
- QEMU virtual machines 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. This format only uses as much host disk space as the guest OS grows to use. Using the snapshot method, the 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 several accelerator plug-ins:
| Virtualizer | Accelerator | Virtualization type | Description | Gentoo package name |
|---|---|---|---|---|
| qemu | tcg | full/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 | paravirtualization | Apple's Hypervisor framework based on Intel VT. | |
| qemu | whpx[1] | hybrid | Microsoft's Windows Hypervisor Platform based on Intel VT or AMD-V. | |
| qemu | kvm | paravirtualization | Linux Type-1 Hypervisor. This is the common choice for hosts using amd64, arm64, or mips[2]. Supports Microsoft Windows. | app-emulation/qemu |
| qemu | haxm[3] | paravirtualization | Intel VT, by Intel Corporation. |
QEMU, if used in conjunction with an accelerator, becomes a Type-1 hypervisor, which runs in Kernel namespace. This allows a user namespace 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 namespace, using its built-in binary translator TCG (Tiny Code Generator). Using QEMU without an accelerator is relatively inefficient and slow.
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 — describes IPv6 support in QEMU/KVM.
- QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.
- Virtiofs — a shared file system that lets virtual machines access a directory tree on the host
- QEMU/Options — describes some of the options useful for configuring QEMU virtual machines.
- QEMU/OS2WarpV3 guest
- QEMU/Windows guest — setup of a Windows guest using 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'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 --extended-regexp "vmx|svm" "/proc/cpuinfo"For a period, manufacturers were shipping with virtualization turned off by default in the system's firmware. Toggling this feature in the firmware may require full removal of power from the system to take effect.
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.
Different guest (virtualized) OS may require additional kernel options. These are covered in the corresponding Usage section.
General setup --->
Timers subsystem --->
<*> High Resolution Timer Support
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 is rebooted.
[*] Virtualization --->
<*> Kernel-based Virtual Machine (KVM) support
This includes support for ARM64 processors.
Processor Support
[*] Virtualization --->
<M> KVM for Intel processors support
[*] Virtualization --->
<M> KVM for AMD processors support
If both KVM support for Intel processors and KVM support for AMD processors are set to be built into the kernel (
*), an error message will be returned by kprint at early boot. Since the system can only have one processor type: Intel or AMD. Enabling one or both options as modules (M) will solve this issue.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:
/usr/src/kernel-kconfig-qemu-host.configCONFIG_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:
/usr/src/kernel-kconfig-qemu-host-optional.configCONFIG_VHOST_NET=y
CONFIG_HIGH_RES_TIMERS=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"
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):
Device Drivers --->
[*] VHOST drivers --->
<*> Host kernel accelerator for virtio net
Device Drivers --->
[*] Network device support --->
[*] Network core driver support
<*> Universal TUN/TAP device driver support
Needed for 802.1d Ethernet bridging:
[*] 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)[4]
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
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 |
X
|
Add support for X11 |
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 |
passt
|
Enable TCP/IP in hypervisor via net-misc/passt |
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-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 |
valgrind
|
Enable annotations for accuracy. May slow down runtime slightly. Safe to use even if not currently using dev-debug/valgrind |
vde
|
Enable VDE-based networking |
verify-sig
|
Verify upstream signatures on distfiles |
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 |
wayland
|
Enable dev-libs/wayland backend |
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 |
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 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:
/etc/portage/package.use/qemuapp-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/qemuConfiguration
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
| name | description |
|---|---|
| G_MESSAGES_DEBUG | Enables debug messages for components using GLib's logging system. If set to all, it outputs to stderr. Other options are all, QEMU, libvirt, gtk, and pulse. Use comma to separate multiple option. |
| LISTEN_FDS | Number of file descriptors passed. Used with QEMU activated by systemd. |
| LISTEN_PID | PID of the receiving process (usually set to the current PID). Used with QEMU activated by systemd. |
| QEMU_AUDIO_DRV | Specifies the audio backend driver to use (options are alsa, pa, oss, none). |
| XDG_RUNTIME_DIR | Specifies where user-specific runtime files and sockets should be stored (e.g., /run/user/UID/). Commonly used by Wayland, PulseAudio, or virt-manager. |
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:
user $ls "/usr/bin/qemu-system-"*/usr/bin/qemu-system-aarch64 /usr/bin/qemu-system-mips /usr/bin/qemu-system-rx /usr/bin/qemu-system-alpha /usr/bin/qemu-system-mips64 /usr/bin/qemu-system-s390x /usr/bin/qemu-system-arm /usr/bin/qemu-system-mips64el /usr/bin/qemu-system-sh4 /usr/bin/qemu-system-avr /usr/bin/qemu-system-mipsel /usr/bin/qemu-system-sh4eb /usr/bin/qemu-system-cris /usr/bin/qemu-system-nios2 /usr/bin/qemu-system-sparc /usr/bin/qemu-system-hppa /usr/bin/qemu-system-or1k /usr/bin/qemu-system-sparc64 /usr/bin/qemu-system-i386 /usr/bin/qemu-system-ppc /usr/bin/qemu-system-tricore /usr/bin/qemu-system-loongarch64 /usr/bin/qemu-system-ppc64 /usr/bin/qemu-system-x86_64 /usr/bin/qemu-system-m68k /usr/bin/qemu-system-ppc64le /usr/bin/qemu-system-x86_64-microvm /usr/bin/qemu-system-microblaze /usr/bin/qemu-system-riscv32 /usr/bin/qemu-system-xtensa /usr/bin/qemu-system-microblazeel /usr/bin/qemu-system-riscv64 /usr/bin/qemu-system-xtensaeb
Permissions
In order to run a KVM-accelerated virtual machine without root privileges, one can add normal users to the kvm group:
root #gpasswd -a larry kvmCreation of a disk image
To create a raw disk image with 4 GiB size:
user $qemu-img create -f raw "/home/larry/qemu/my-systems-disk-image.img" 4GFormatting 'my-systems-disk-image.img', fmt=raw size=4294967296
user $ls -lhtotal 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/qemu/my-systems-disk-image.img" -o nocow=on 4GFormatting 'my-systems-disk-image.img', fmt=raw size=4294967296 nocow=on
user $ls -lhtotal 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[5].
The following will create a qcow2 disk image (useful, if the host filesystem does not support sparse files):
user $qemu-img create -f qcow2 "/home/larry/qemu/my-systems-disk-image.qcow2" 4GFormatting '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 -ltotal 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 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:
root #losetup --find --partscan --show "/home/larry/qemu/my-systems-disk-image.img"/dev/loop0
- The parameter
--findfinds the first unused loop device. - The parameter
--partscanforces 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
--showdisplays the name of the assigned loop device, if the parameter--findis used.
Attached loop devices can be listed with the following command:
root #losetup --listNAME 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"Error: /dev/loop0: unrecognised disk label Model: Loopback device (loopback) Disk /dev/loop0: 4096MiB Sector size (logical/physical): 512B/512B Partition Table: unknown Disk Flags:
Create a new partition table (msdos disk label):
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"Model: Loopback device (loopback) Disk /dev/loop0: 4096MiB Sector size (logical/physical): 512B/512B Partition Table: msdos Disk Flags: Number Start End Size Type File system Flags
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"Model: Loopback device (loopback) Disk /dev/loop0: 4096MiB Sector size (logical/physical): 512B/512B Partition Table: msdos Disk Flags: Number Start End Size Type File system Flags 1 2.00MiB 4095MiB 4093MiB primary
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 onAll partition flags can be found in the column "Flags":
root #parted "/dev/loop0" "unit mib print"Model: Loopback device (loopback) Disk /dev/loop0: 4096MiB Sector size (logical/physical): 512B/512B Partition Table: msdos Disk Flags: Number Start End Size Type File system Flags 1 2.00MiB 4095MiB 4093MiB primary boot
Create the ext4 filesystem, which was declared via parted earlier:
root #mkfs.ext4 "/dev/loop0p1"mke2fs 1.47.2 (1-Jan-2025)
Discarding device blocks: done
Creating filesystem with 1047808 4k blocks and 262144 inodes
Filesystem UUID: 0e344af7-6f7b-4d27-8238-89d46a5920d6
Superblock backups stored on blocks:
32768, 98304, 163840, 229376, 294912, 819200, 884736
Allocating group tables: done
Writing inode tables: done
Creating journal (16384 blocks): done
Writing superblocks and filesystem accounting information: done
Mount it at /mnt:
root #mount /dev/loop0p1 /mntroot #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 boot loader on the loop device and advice it to install its files to /mnt/boot/grub/:
root #grub-install --target="i386-pc" --boot-directory="/mnt/boot/" "/dev/loop0"root #tree -F "/mnt/boot/grub/"/mnt/boot/grub/ ├── fonts/ │ └── unicode.pf2 ├── grubenv ├── i386-pc/ │ ├── acpi.mod │ ├── adler32.mod │ ├── affs.mod │ ├── afs.mod │ ├── afsplitter.mod │ ├── ahci.mod │ ├── all_video.mod │ ├── aout.mod │ ├── archelp.mod │ ├── ata.mod [...]
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 --listNAME 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 31813This 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:
user $qemu-system-x86_64 -vnc "unix:/run/user/$(id --user)/qemu-vnc.sock" -enable-kvm -cpu host -drive "file=/home/larry/qemu/my-systems-disk-image.img,format=raw" -m 2GSet the file permissions of /run/user/$(id --user)/qemu-vnc.sock appropriately, in order to protect the VNC server from unauthorized access! If the virtual machine is started with the parameter
-vnc :0, it will listen on port 5900 on all interfaces without password protection! The parameter :0 represents the first display of the host machine, which may be mistaken as a port number!A CD-ROM installation or boot medium can be added via the parameter
-cdrom. For example: -cdrom filename.isoConnecting 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:
user $vncviewer "/run/user/$(id --user)/qemu-vnc.sock"TigerVNC viewer v1.15.0 Built on: 2025-05-13 12:30 Copyright (C) 1999-2025 TigerVNC team and many others (see README.rst) See https://www.tigervnc.org for information on TigerVNC. Tue May 13 14:44:36 2025 DecodeManager: Detected 4 CPU core(s) DecodeManager: Creating 4 decoder thread(s) CConn: Connected to socket /run/user/1000/qemu-vnc.sock CConnection: Server supports RFB protocol version 3.8 CConnection: Using RFB protocol version 3.8 CConnection: Choosing security type None(1) CConn: Using pixel format depth 24 (32bpp) little-endian rgb888 CConn: SetDesktopSize failed: 3
This will open a separate window, where one gets greeted with a GRUB shell, which was installed via grub-install earlier:
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:
qemu-system-x86_64: CPU model 'host' requires KVM or HVF
In order to fix this, use the parameter -enable-kvm, which will enable KVM full virtualization support:
user $qemu-system-x86_64 -cpu host -enable-kvm [...]kvm: already loaded the other module
Sometimes, during the early boot splash, the following error message may be seen:
kvm: already loaded the other module.
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:
root #modprobe tunIf 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:
/etc/modules-load.d/qemu-modules.conftun
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:
/etc/portage/package.use/qemuapp-emulation/qemu spice
Then recompile the QEMU:
root #emerge --ask --changed-use app-emulation/qemuQEMU 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:
Error starting domain: unable to set socket security context 'system_u:system_r:svirt_t:s0:c123,c456': Invalid argument
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:
<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>
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:
root #emerge --ask --oneshot sys-libs/zlib dev-libs/glibroot #emerge --ask --oneshot app-emulation/qemuWindows 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.
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 kernel parameter kvm.ignore_msrs=1 on the kernel command line or as a parameter to the kvm module:
This parameter should only be set, if there are still undefined MSRs. If there are any, then it is probably a bug, which needs to be reported to the software vendor or KVM/QEMU maintainers.
/etc/modprobe.d/kvm.confoptions kvm ignore_msrs=1
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.
While the parameter
ignore_msrs can be a quick fix for a decent amount of Blue Screens related to MSR accesses, it is likely, that this can be addressed properly, by enabling the appropriate kernel parameter, as documented above.Guest system breaks sound
Attempting sound playback may output either choppy sound or none at all. A possible fix is to use these parameters[6]:
user $qemu-system-x86_64 -audiodev pa,id=Sound -device intel-hda -device hda-output,audiodev=Sound [...]Removal
Unmerge
root #emerge --ask --depclean --verbose app-emulation/qemuThere may be image files left behind after the removal of the QEMU package.
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 Virtual Machine (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