From Gentoo Wiki
Jump to: navigation, search

QEMU (Quick EMUlator) is a generic, open source machine emulator and virtualizer. 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).


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 affect after the system has booted to a KVM enabled kernel.


Activate the following kernel options:

[*] Virtualization  --->
    <*>   Kernel-based Virtual Machine (KVM) 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
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
KERNEL Optional advanced networking support
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
[*] Networking support  --->
        Networking options  --->
            <*> The IPv6 protocol
            <*> 802.1d Ethernet Bridging

python USE flag is needed for file capabilities support:

KERNEL Enabling Linux 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:

KERNEL Enabling ext4 kvm_stat support
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

accessibility Adds support for braille displays using brltty local
aio Enables support for Linux's Async IO local
alsa Enable alsa output for sound emulation local
bluetooth Enable Bluetooth Support global
bzip2 Use the bzlib compression library global
caps Use Linux capabilities library to control privilege global
curl Support ISOs / -cdrom directives vis HTTP or HTTPS. local
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 global
fdt Enables firmware device tree support local
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) global
glusterfs Enables GlusterFS cluster fileystem via sys-cluster/glusterfs local
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. local
gtk Add support for x11-libs/gtk+ (The GIMP Toolkit) global
gtk2 Use gtk-2 instead of gtk-3 local
infiniband Enable Infiniband RDMA transport support global
iscsi Enable direct iSCSI support via net-libs/libiscsi instead of indirectly via the Linux block layer that sys-block/open-iscsi does. local
jpeg Enable jpeg image support for the VNC console server local
lzo Enable support for lzo compression global
ncurses Enable the ncurses-based console local
nfs Enable NFS support local
nls Add Native Language Support (using gettext - GNU locale utilities) global
numa Enable NUMA support local
opengl Add support for OpenGL (3D graphics) global
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. local
png Enable png image support for the VNC console server local
pulseaudio Enable pulseaudio output for sound emulation local
python Add optional support/bindings for the Python language global
rbd Enable rados block device backend support, see http://ceph.newdream.net/wiki/QEMU-RBD local
sasl Add support for the Simple Authentication and Security Layer global
sdl Enable the SDL-based console local
sdl2 Use libsdl2 instead of libsdl local
seccomp Enable seccomp (secure computing mode) to perform system call filtering at runtime to increase security of programs global
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur global
smartcard Enable smartcard support global
snappy Enable support for snappy compression local
spice Enable Spice protocol support via app-emulation/spice local
ssh Enable SSH based block device support via net-libs/libssh2 local
static Build the User and Software MMU (system) targets as well as tools as static binaries local
static-user Build the User targets as static binaries local
systemtap Enable SystemTAP/DTrace tracing local
tci Enable the TCG Interpreter which can speed up or slowdown workloads depending on the host and guest CPUs being emulated. In the future it will be a runtime option but for now its compile time. local
test Workaround to pull in packages needed to run with FEATURES=test. Portage-2.1.2 handles this internally, so don't set it in make.conf/package.use anymore global
usb Enable USB passthrough via dev-libs/libusb local
usbredir Use sys-apps/usbredir to redirect USB devices to another machine over TCP local
vde Enable VDE-based networking local
vhost-net Enable accelerated networking using vhost-net, see http://www.linux-kvm.org/page/VhostNet local
virgl Enable experimental Virgil 3d (virtual software GPU) local
virtfs Enable VirtFS via virtio-9p-pci / fsdev. See http://wiki.qemu.org/Documentation/9psetup local
vnc Enable VNC (remote desktop viewer) support global
vte Enable terminal support (x11-libs/vte) in the GTK+ interface local
xattr Add support for getting and setting POSIX extended attributes, through sys-apps/attr. Requisite for the virtfs backend. local
xen Enables support for Xen backends local
xfs Support xfsctl() notification and syncing for XFS backed virtual disks. local

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.


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, you want a softmmu target; user targets execute user-mode code only - i.e. you wish to execute a single ELF binary from a different architecture, rather than an entire OS.


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

root #emerge --ask app-emulation/qemu



Basic networking support can be configured "out of the box" by creating a vlan with the following options.

-net nic,vlan=0 -net user,vlan=0
As of QEMU 0.12 the `-net` method is considered obsolete, although it continues to work.[1]

A more advanced networking concept is outlined below, which enables guest access to an external network and also works with both wired and wireless adapters on the host. If desired, a DHCP server can also be setup on the host to allow for dynamic guest IP configurations. There are many different tutorials available online to further understand these concepts.[2][3][4][5][6][7][8][9]

Qemu network diag.png

Required packages

This example networking configuration needs some extra software installed:

root #emerge --ask net-firewall/iptables

Host configuration

Creating TUN/TAP device

This allows the guest to communicate with the bridge. QEMU's default group is kvm, ensure that the correct group is given permissions to control the TAP. Enabling promiscuous mode (promisc) for the adapter might be unnecessary.

root #ip tuntap add dev tap0 mode tap group kvm
root #ip link set dev tap0 up promisc on
root #ip addr add dev tap0
Create network bridge

Creating a network bridge seems necessary, even if only 1 guest is configured. Create the bridge and add each TAP to it. Spanning tree protocol (stp) is disabled because there is only 1 bridge.[10]

root #ip link add br0 type bridge
root #ip link set br0 up
root #ip link set tap0 master br0
root #echo 0 > /sys/class/net/br0/bridge/stp_state
root #ip addr add dev br0
Packet Forwarding and NAT

Allows for proper packet routing.

root #sysctl net.ipv4.conf.tap0.proxy_arp=1
root #sysctl net.ipv4.conf.eth1.proxy_arp=1
root #sysctl net.ipv4.ip_forward=1
root #iptables -t nat -A POSTROUTING -o br0 -j MASQUERADE
root #iptables -A FORWARD -i br0 -o eth1 -m state --state RELATED,ESTABLISHED -j ACCEPT
root #iptables -A FORWARD -i eth1 -o br0 -j ACCEPT

Guest configuration

The following should be added to the configuration.

-net nic,vlan=0 -net tap,ifname=tap0,script=no,downscript=no

After starting the guest, the IP should be configured to be on the vlan and the gateway should be the IP given to the bridge. The exact process will vary based on OS.


For IPv6 networking see the IPv6 subarticle.


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 http://sourceforge.net/projects/aqemu Graphical interface for QEMU and KVM emulators, using Qt4
libvirt app-emulation/libvirt http://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 http://f1ash.github.io/qt-virt-manager/ A graphical user interface for libvirt written in Qt4/5
virt-manager app-emulation/virt-manager http://virt-manager.org A graphical tool for administering virtual machines


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.


"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.

See also

External resources