Gentoo Wiki




QEMU emulates a number of different platforms ( ARM systems, IA-32 (x86) PCs, AMD64 PCs, MIPS R4000, Sun's SPARC sun3 and PowerPC (PReP and Power Macintosh))

KQEMU is a kernel module accelerator for QEMU allowing virtualization techniques used by similar software (such as VMWare or Microsoft Virtual PC). KQEMU used to be proprietary, but since version 1.3.0pre10 (released on February 5, 2007) it is available under GNU GPL.

The QVM86 project was attempting to create an GPL'd virtualization module for QEMU, but it is now abandoned (you can use either KQEMU or InnoTek's VirtualBox instead).

Two common uses for QEMU are for running Windows atop Gentoo or Gentoo atop Windows. This can be useful for software that doesn't yet support the other platform and doesn't work well with compatibility layers (eg wine or cygwin). QEMU is also useful for application testing as it avoids the need to reboot.


Warning: Users have had mixed results attempting to compile QEMU under GCC 4.x. At the current time, Upstream does not support compiling QEMU under GCC4, due to code complications. See There is a patch in that bug report which may help with compiling on gcc 4.x

Ticket says RESOLVED.

Warning: If you built your kernel with gcc4 and you build the kqemu module with gcc3, it will probably fail to load.

Build with gcc3

The best way to build qemu is with gcc-3.3. gcc is a "slotted" ebuild, which means one can have gcc-3.3 versions installed alongside gcc-4.x versions. If you once used gcc-3.3 you may already have it installed. The following command (requires that you have installed 'app-portage/gentoolkit') will show you all the gcc versions (for your native architecture) which you have installed on your system:

Code: list installed gcc versions
# equery list --installed --exact-name 'sys-devel/gcc' 

If you have no gcc-3.3.x installed, type:

Code: emerge gcc-3.3
# emerge -av sys-devel/gcc:3.3
Note: As at 24 Nov 2007, GCC-3.3 is ~amd64 and won't compile. AMD64 users will need to use GCC-3.4. As at 30 Jan 2008, GCC-3.3 is required for x86, building it with GCC-3.4 seems to fail
Code: emerge gcc-3.4
# emerge -av sys-devel/gcc:3.4

The colon is a new-ish portage feature which tells portage to give you the latest point revision from the specified "slot." The colon will go into your world-file and will bring you peace and happiness in the future thereby. Now switch the active system compiler to gcc-3.3:

Code: Switch to gcc-3.3 with gcc-config
# gcc-config -l
# gcc-config x86_64-pc-linux-gnu-3.3.6 (but substitute whatever 3.3.x version the previous command showed)
# source /etc/profile

Note: if you are using hardened-toolchain, you need to set up hardenednopie version (i.e. gcc-config x86_64-pc-linux-gnu-3.4.6-hardenednopie)
Emerge the qemu packages as per below instructions and when you are done switch back to gcc 4 with.

Code: Switch back to gcc4
# gcc-config x86_64-pc-linux-gnu-4.1.2

Build with gcc4

Warning: Some users have had problems compiling and using Qemu with GCC4. Even if it builds correctly, segmentation faults can occur. You are recomended to compile Qemu with GCC3.
Note: GCC4 users may need to modify their CFLAGS temporarily, simplifying - especially on Athlon-XP machines. "-march=athlon-xp" needs to change to "-mtune=athlon-xp".
Note: As of Nov 18, 2007 0.9 versions are reported to build correctly.
As of Dec 10, 2007 qemu-softmmu-0.9.0-r1.ebuild explicitly denies GCC-4 on line 47 of the ebuild. Please note forcing the ebuild to try and compile did not work. Even if it had there were quite a few pointer warnings that made me uneasy.


If you want to have ANY graphical output in QEMU, you'll have to add the "sdl" use flag to the list:

File: /etc/portage/package.use
app-emulation/qemu-softmmu sdl

To install QEMU, just emerge it, but first make sure you have "sdl" enabled.

Code: For just QEMU
# emerge qemu -av

Note: If you just want to run Windows under x86 Linux (ie. you don't need cross-CPU emulation), emerge qemu-softmmu instead.


Or if you want KQEMU, you'll have to add the use flag to the list:

File: /etc/portage/package.use
app-emulation/qemu-softmmu kqemu sdl

Then emerge it and load the module

Box $ /bin/su
Box # emerge kqemu
Box # modprobe kqemu major=0

NOTE: If you compiled your kernel with gcc4 then you will get an error when you try to load the module because your kernel needs modules to be compiled with gcc4 to load them, simply switch back and emerge kqemu again:

File: Gcc4 Kernel Module load error
FATAL: Error inserting kqemu (/lib/modules/ Invalid module format
Code: For KQEMU+GCC4 Kernel
Box $ gcc-config x86_64-pc-linux-gnu-4.1.1
Box # source /etc/profile 
Box # emerge -av kqemu
Box # modprobe kqemu major=0

You will probably want to load the module every time you boot so you don't have to remember to do that by hand each time. To do so, edit your /etc/modules.autoload.d/kernel-2.6 (or kernel-2.4) file or load it in the start script of QEMU (see below)

File: /etc/modules.autoload.d/kernel-2.6
kqemu major=0

Finally, add your user to the qemu group so you can access kqemu.

Box #gpasswd -a [your_user] qemu

By default QEMU just runs user-space code with KQEMU. 'qemu -kernel-kqemu' will also run kernel-space code with KQEMU, resulting in a large speed increase.

To emulate a non-x86 machine, you should use qemu-system-{arch} to get kqemu working, e.g.

Box #qemu-system-x86_64 -hda /path/to/image -boot X -m xxx 

for x86_64 guests.

To tell if KQEMU was succesfully loaded, use the QEMU console (alt+ctrl+2) and type 'info kqemu'. You should see the following output.

(qemu)info kqemu
kqemu support: enabled for user and kernel code

If you see any other message, kernel KQEMU support is not enabled.

Getting started

Booting from a LiveCD ISO

Code: Booting a LiveCD
$ qemu -cdrom mpentoo.2006.0.iso -boot d -m 128

The -cdrom switch tells QEMU to see the ISO file as a virtual CD-ROM. The -m switch specifies the amount of RAM available for the guest OS.

Installing an OS and booting

Unless you're just testing a Live CD ISO, you'll likely want to create a disk image for QEMU to write to.

You can do so either with dd or by using the qemu-img command.

Code: ~4GB Sparse Disk Image with DD
$ dd of=disk.img count=0 bs=1M seek=4096

or use a resizable COW image. The "qcow2" image format will only take up as much space as is really needed, so the image will be very small in the beginning (not 1.3 GB!). Note: As of version 0.8.3, "qcow2" is the preferred image format, as it supports more features than "qcow".

Code: Dynamic COW Disk Image
$ qemu-img create -f qcow2 /path/to/xp.cow 1300M

To load that disk image but boot from a CD-Rom, use:

Code: 384 is RAM seen by GuestOS
$ qemu -hda /path/to/xp.cow -boot d -cdrom /dev/cdrom -m 384 -localtime

You may need to adjust the amount of memory (-m 384) for your system.

Note:Make sure to use a larger disk image 1300M is not enough for Windows XP, use at least 4GB minimum. Otherwise you'll have to resize later on, which is time consuming.

To load and boot from that disk image:

Code: 384 is RAM seen by GuestOS
$ qemu -hda /path/to/xp.cow -boot c -m 384 -localtime -k de -usb

Using the emulated OS with ethernet and a valid IP

Qemu provides basic networking functionality by default (-net user), but this does not work with things that need root access, such as ping. To use your host's ethernet connection over the emulated OS you'll need to use TUN/TAP.

You must enable TUN/TAP in your kernel by using the following configuration option:

Linux Kernel Configuration: Enable TUN/TAP support
Device Drivers  ---> 
   Networking support  --->
      <M> Universal TUN/TAP device driver support
Networking  --->
   Networking options  --->
      <*> 802.1d Ethernet Bridging #NOTE : at least for 2.6.20 series
Code: Load TUN/TAP module
modprobe tun

Making a bridge

Setting up a bridge on the host machine for two guests (Example)

Code: Emerge these utilities
# emerge net-misc/bridge-utils sys-apps/usermode-utilities
Code: Create a tun device as follows (2.4 kernel)
# mknod /dev/net/tun c 10 200
Code: Open /etc/conf.d/net for editing
# nano -w /etc/conf.d/net

Manually set up IP information for br0

Static IP:

File: /etc/conf.d/net
config_eth0=( "null" )
config_br0=( "" )
brctl_br0=( "setfd 0" "sethello 1" "stp off" )
routes_br0=( "default gw" )


File: /etc/conf.d/net
config_eth0=( "null" )
config_br0=( "dhcp" )
dhcpcd_br0="-t 10"
brctl_br0=( "setfd 0" "sethello 1" "stp off" )
Code: Add net.br0 to the default runlevel
# cd /etc/init.d && ln -s net.lo net.br0 && rc-update add net.br0 default
Code: Add this iptables rule to your firewall
# /sbin/iptables -A INPUT -i br0 -j ACCEPT
Code: Restart the network
# /etc/init.d/net.eth0 stop && /etc/init.d/net.br0 start && ifconfig br0 && ifconfig eth0

Create a guest01-ifup and guest02-ifup scripts

File: nano -w guest01-ifup
# ____Address: (guest01) and (guest02)
# ____Netmask:
# ___Wildcard:
# ____Gateway:

if test $(/sbin/ifconfig | grep -c $1) -gt 0; then
        /sbin/brctl delif br0 $1
        ifconfig $1 down

/sbin/ifconfig $1 promisc up
/sbin/brctl addif br0 $1
Code: Create a persistent TAP interfaces
# tunctl -u root -t tap0
# tunctl -u root -t tap1

Comment: I would recommend that you create the tap device with ownership to the user running qemu as follows tunctl -u <user> -t tap0 This prevents having to run qemu as root in >=2.6.18 --Mistik1 00:18, 26 February 2007 (UTC) Comment: If you use QEmu 0.9.0 or higher, recommend to end the ifup script with exit 0 statement, because the QEmu is not starts guest, when you not return explicite 0 exit code --George Hron 15:13, 22 September 2007 (CEST)

Now start QEMU for each guest

Code: Guest 1
# /usr/local/bin/qemu -localtime -m 512m -cdrom /dev/cdrom \
-net nic,macaddr=52:54:00:12:34:56 -net tap,ifname=tap0,script=guest01-ifup \
-boot c -hda img=guest01.img
Code: Guest 2
# /usr/local/bin/qemu -localtime -m 512m -cdrom /dev/cdrom \
-net nic,macaddr=52:54:00:12:34:57 -net tap,ifname=tap1,script=guest02-ifup \
-boot c -hda guest02.img

Attention: Choose a different MAC address for guest01 and guest02

The "ifname=tap0" and "ifname=tap1" are the argument $1 used in guest-ifup script

Code: Verify if the network is setup properly for each guest
# ifconfig tap0 && ping && ifconfig tap1 && ping

Using TUN/TAP interface as a normal user

The above examples all assume that you're running Qemu as root. If you want to run Qemu with a tap interface as a non-root user there are two requirements:

The first may be accomplished by wrapping qemu startup in a shellscript like this:

Code: Creating a user-owned TAP interface
set -x
TAP=$(sudo tunctl -b -u $User)
# qemu command goes here
sudo tunctl -d $TAP

Since you've gone to the bother of creating a wrapper script that creates the interface, you might as well configure it there as well. This saves the trouble of having to install an "ifup" script for Qemu:

Code: Creating and configuring a user-owned TAP interface
set -x
TAP=$(sudo tunctl -b -u $User)
sudo /sbin/ifconfig $TAP promisc up
sudo /sbin/brctl addif br0 $TAP
qemu -hda w2kdisk.img -net nic -net tap,ifname=$TAP,script=no
sudo tunctl -d $TAP

Creating a group to simplify things

The wrappers above solve one problem but require the users running Qemu to have "sudo" permission for a few commands: ifconfig, tunctl, and brctl. There is still also the problem that the users running Qemu also need to have read/write permissions for /dev/net/tun. The cleanest way to solve these problems is to create a new user group (using groupadd) that is going to have r/w permission on /dev/net/tun and will also have "sudo" permissions for the commands required to manipulate network devices.

For our example, a group named "vmnet" has been added, and the user "grante" has been added to that group:

File: /etc/group

[If you already have a qemu group, that could be used instead.]

Allow vmnet group to run the required commands without passwords:

File: /etc/sudoers
%vmnet	ALL=(ALL)	NOPASSWD: /sbin/ifconfig, /sbin/brctl, /usr/bin/tunctl

That should take care of running the wrapper script without having to enter a password (handy if you want to be able to start Qemu from a desktop menu).

Setting group permissions on /dev/net/tun

The final problem is to make sure that the users running Qemu have read/write permission for /dev/net/tun. The permissions on /dev/net/tun are controlled by a rule in /etc/udev/rules.d/50-udev.rules that looks like this:

File: /etc/udev/rules.d/50-udev.rules
KERNEL=="tun",		NAME="net/%k",	MODE="0660", OPTIONS+="ignore_remove"

Change that rule so that it sets the group of the tun device to be that of our new group:

File: /etc/udev/rules.d/50-udev.rules
KERNEL=="tun",		NAME="net/%k", GROUP="vmnet", MODE="0660", OPTIONS+="ignore_remove"

The change won't take effect until the next boot, so in the

meantime you can do
chown root:vmnet /dev/net/tun"

to get things working immediately.

NB: that rules file will be overwritten the next time udev is updated, so pay attention when emerging udev.

Use VDE Switch

First of all you need to emerge net-misc/vde to have the vde_switch utility:

Code: emerge vde
emerge net-misc/vde

Then you need to configure tap interface:

Code: Create tap interface
cd /etc/init.d/
ln -s net.lo net.tap0
Code: /etc/conf.d/net
config_tap0=( " netmask " )

To bring interface up you need to execute:

Code: /etc/conf.d/net
/etc/init.d/vde start
/etc/init.d/net.tap0 start

Now you can start qemu as usual.



If many keys (such as the F-keys, the arrow keys, and many combinations) don't work or work strange, add "-k en-us" to options of qemu

For installing Windows 2000, try using the -win2k-hack to avoid out of space errors. This only applies to the Windows installation process and should not be used once Windows 2000 is installed, since it causes disk I/O to be very slow in the guest.

Also, when you have problems with compiling QEMU try a gcc 3.x . It seems like even the newest QEMU (0.8.2) doesn't support the gcc 4.x releases - However, 0.8.1 is known to work. Also it is possible to emerge KQEMU with GCC 4.x and other QEMU packages with GCC 3.x. Works for me and couple of other people I know.

If you still have problem compiling QEMU with gcc 3.x, try an other gcc 3.x. Gcc 3.3.6 worked for 'me', but not gcc 3.4.6.

If you are having problems with QEMU crashing or restarting while trying to install Windows XP as the guest OS while running the the kqemu module, try installing Windows without the kqemu module running. As documented in the forums, kqemu seems to cause problems with the install process. After you get Windows installed (which will take a while), you can resume using kqemu.

As of QEMU 7.1, there seems to be a problem with the mouse cursor getting stuck in the lower right corner of the emulated X11 screen. Exporting SDL_VIDEO_X11_DGAMOUSE=0 in your environment fixes the issue.

Resizing image

For qcow images, since it can't yet be resized natively.

Code: Resize image
qemu-img convert -f qcow2 xp.cow -O raw xp.raw
dd bs=1 if=/dev/zero of=xp.raw seek=7G count=1 conv=notrunc
Note: resizing to a total size of 7G

verify that xp.raw is the correct size

Code: raw image size
qemu-img info xp-qemu-img.raw 
  image: xp.raw
  file format: raw
  virtual size: 7.0G (7516192768 bytes)
  disk size: 3.1G

Get a copy of gparted either burned to a CD or iso image. Resize the NTFS partition (use /dev/cdrom or gparted-live-0.X.Y-Z.iso file)

Code: use gparted cdrom to resize ntfs partition
qemu -hda xp.raw -cdrom /dev/cdrom -boot d

check that windows has the disk size correct and that everything is ok

Code: boot raw image
qemu -hda xp.raw
Note: When windows boots up it does an chkdsk, and new hardware found

convert image from raw back to cow2, removing the original image

Code: convert image back to cow
qemu-img convert -f raw xp.raw -O qcow2 xp.cow

Tips and Tricks

Code: switching CD-ROMs
eject cdrom
change cdrom /dev/cdrom

See also

Retrieved from ""

Last modified: Fri, 26 Sep 2008 06:33:00 +0000 Hits: 73,592