This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
QEMU
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.
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).
Installation
BIOS and UEFI firmware
In order to utilize KVM either Vt-x or AMD-V 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 visualization 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 BIOS. Note that changing this feature in the BIOS 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
Activate the following kernel options:
[*] Virtualization ---> <*> Kernel-based Virtual Machine (KVM) support
[*] Virtualization ---> <M> KVM for Intel processors support
[*] Virtualization ---> <M> KVM for AMD processors support
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.Needed for vhost-net
USE flag (recommend):
[*] Virtualization ---> <*> 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
python
USE flag is needed for file capabilities support:
Kernel hacking ---> Compile-time checks and compiler options ---> [*] Debug Filesystem
When using the ext4 filesystem, enable the filecaps
USE flag if stats support is needed:
File systems ---> <*> The Extended 4 (ext4) filesystem [*] Ext4 Security Labels
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 |
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 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 |
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. |
xen
|
Enables support for Xen backends |
zstd
|
Enable support for ZSTD compression |
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.USE_EXPAND
See app-emulation/qemu for a list of possible values for QEMU_USER_TARGETS and QEMU_SOFTMMU_TARGETS.
For each target specified, a qemu executable will be built. Normally, a softmmu
target will work; user
targets execute user-mode code only - i.e. the goal is to execute a single ELF binary from a different architecture, rather than an entire OS.
In order to enable QEMU_USER_TARGETS and QEMU_SOFTMMU_TARGETS you have to edit the make.conf file.
make.conf
QEMU_SOFTMMU_TARGETS="arm x86_64 sparc" QEMU_USER_TARGETS="x86_64"
Otherwise you can always edit the package.use file.
package.use
qemu_softmmu_targets_m68k 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
Networking
For Networking configuration, see the networking options documentation.
IPv6
For IPv6 networking see the IPv6 subarticle.
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
Front ends
To make life easier, there are multiple user-friendly front ends to QEMU:
Name | Package | Homepage | Description |
---|---|---|---|
AQEMU | app-emulation/aqemu | https://sourceforge.net/projects/aqemu/ | Graphical interface for QEMU and KVM emulators, using Qt5. |
GNOME 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 | app-emulation/qtemu | http://qtemu.sourceforge.net/ | A graphical user interface for QEMU written in Qt4. |
qt-virt-manager | app-emulation/qt-virt-manager | https://f1ash.github.io/qt-virt-manager/ | A graphical user interface for libvirt written in Qt4/5. |
virt-manager | app-emulation/virt-manager | https://virt-manager.org | A graphical tool for administering virtual machines. |
virt-manager
When using virt-manager the
usbredir
USE flag must be enabled for qemu to work properly.To run as a normal user, after emerging, ensure they are in the libvirt group:
root #
groupadd libvirt
root #
usermod -a -G libvirt <user>
Uncomment the following lines from the libvirtd configuration file:
/etc/libvirt/libvirtd.conf
unix_sock_group = "libvirt" unix_sock_ro_perms = "0777" unix_sock_rw_perms = "0770"
Be sure to have the user log out then log in again for the new group settings to be applied.
Issue the following command to restart the libvirtd service under OpenRC:
root #
/etc/init.d/libvirtd restart
Issue the following command to restart the libvirtd service under Systemd:
root #
systemctl restart libvirtd
virt-manager should now be launchable as a regular user.
If permission denied issues are experienced when loading ISO images user directories (somewhere beneath /home/) then the /var/lib/libvirt/images/ directory can be used to store the images.
Usage
The following sub-articles provide instructions on QEMU usage:
- Usage options - Contains common options used with QEMU.
- Linux guest - Describes the configuration steps needed to setup Linux to run on QEMU.
- Windows guest - Describes the configuration steps needed to setup Windows to run on QEMU.
- OS2WarpV3 guest - Describes the configuration steps needed to setup OS2WarpVs=3 to run on QEMU.
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:
/etc/modules-load.d/qemu-modules.conf
tun
See also
- QEMU/KVM_IPv6_Support — describes IPv6 support in QEMU/KVM
- Comparison of virtual machines — compares the features of several platform virtual machines
External resources
- http://www.linux-kvm.org/page/KvmOnGentoo - The Gentoo article on the KVM wiki
- http://wiki.qemu.org/Main_Page - The Official QEMU wiki
- http://www.tuxradar.com/content/howto-linux-and-windows-virtualization-kvm-and-qemu - A TuxRadar howto.