QEMU - Debian - Linux - TUN/TAP - network bridge

My first experience with QEMU was the Debian package which didn't seem to work very well. So instead I got the source code from the QEMU website and compiled version 0.6.0. Which worked better, but still seemed to have problems. The later version 0.7.0 worked very well. Again I compiled from source.

For the older version of this guide covering version 0.7 and earlier.

Upgrading to version 0.8.0 wasn't so good initially. A lot of the network runtime options have changed, which are probably for the best. The last code base I had working has been 0.8.1. Most interestingly is the VNC support. So far I haven't got my old images to work with the latest version of QEMU. Although I haven't really given them a proper test.

For some infomation relating to installing various OSes

Using the kernel module kqemu

Using the kqemu kernel module makes big differences to performance. So it's well worth using, but unfortently it is closed source at the moment. Certainly it's a shame it's not open source, personally I feel that it would be better if were opened up. Have a read about it on the website

Anyway if you want to get it working, just follow the guide. Should be straight forward unless you have never compiled your own kernel.

It should be noted that kqemu doesn't work with paravirtualisation offered by Xen. Although I'd recommend having a look at Xen. Once full virtualisation is possible on chips like Intel Vanderpool and AMD Pacifica then it should be possible to run kqemu.

Accessing the network from a QEMU VM with TUN/TAP

There's a good chance you'll want your VM to access the netowrk. You can use the -net user option which works well if you just want a NAT type of connection through the host IP. But it you want your VM to have it's own IP then you need to setup a bridge. This is where this guide gets a bit Debian specific. I assume you have QEMU installed and that it works.


First off you need to configure a network bridge. Which requires the bridge-utils package. For the TUN/TAP you need to check your kernel config file for CONFIG_TUN=m or CONFIG_TUN=y.

# grep CONFIG_TUN= /boot/config-`uname -r`

Also you need to make sure /dev/net/tun exists. To make it:

# mknod /dev/net/tun c 10 200

The bridge-utils package has good docs in Sarge which you can find in /usr/share/doc/bridge-utils/. To save you having to manually bring up the bridge you can configure your network interface card to act part of a bridge via the usual /etc/network/interface config file. Note that any NIC you plan to use in the bridge should not have a separate config. So at least comment it out. Here is an example of what I have.

# /etc/network/interface
# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

# The loopback network interface
auto lo
iface lo inet loopback

# The bridge network interface(s)
auto br0
iface br0 inet static
bridge_ports eth0
bridge_fd 9
bridge_hello 2
bridge_maxage 12
bridge_stp off

#auto eth0
#iface eth0 inet dhcp

If you wanted to bridge over more physical networks you can just add more devices to bridge_ports eth0 eth1 eth2 eth3... But this is going out of the scope of this guide.

Sudo setup

Your don't want to run QEMU as root so you'll probably want to install sudo to automate things. This is becasue the default action for QEMU is to run the /etc/qemu-ifup script to bring up the tun/tap device. Which you need to create. Part of that script is to bring up the tun0 interface via ifconfig and add it to the bridge which normally only root can do. So after installing sudo, you need to run visudo to edit /etc/sudoers. Don't edit it directly, use visudo. Here is my example sudoers file.

# /etc/sudoers
# This file MUST be edited with the 'visudo' command as root.
# See the man page for details on how to write a sudoers file.

# Host alias specification

# User alias specification

# Cmnd alias specification
Cmnd_Alias      SHUTDOWN=/sbin/shutdown, \
			/sbin/halt, \
Cmnd_Alias      QEMU=/sbin/ifconfig, \
			/sbin/modprobe, \

# User privilege specification
root    ALL=(ALL) ALL


The %local line refers to the group 'local', which you can add users to. I've got it setup so that people can shut the machine down without requiring root access.

/etc/qemu-ifup script

Next you'll need to create the /etc/qemu-ifup script. QEMU passes the script one parameter, which is the device it's going to use. So here is a simple shell script to make things work.


echo "Executing /etc/qemu-ifup"
echo "Bringing up $1 for bridged mode..."
sudo /sbin/ifconfig $1 promisc up
echo "Adding $1 to br0..."
sudo /usr/sbin/brctl addif br0 $1
sleep 2


Make sure you chmod 755 /etc/qemu-ifup so that all users can execute the script. As long as your bridge is properly configured in /etc/network/interface and sudo works then this should just work.

Running QEMU

All being well you should be able to run QEMU and it will automatically pickup a tun/tap device. But to automate a little futher I wrote another script to run QEMU with the right parameters so I don't have to remember them. Also this loads the kernel module kqemu. Of course you could just add kqemu to /etc/modules so it's always loaded at boot up. But you might not always want to load a closed source kernel driver. So here is the helper script.


ARGS="-hda win2k.img -boot c -net nic,vlan=0 -net tap,vlan=0,ifname=tap0,script=/etc/qemu-ifup -m 256 -localtime"

echo "Loading kqemu kernel module..."
sudo modprobe kqemu
echo "...."

echo "Starting QEMU with..."
echo $ARGS
echo "...."
exec qemu $ARGS


Configuring NIC in guest OS

When you're configuring the network card in the guest OS, make sure you specify an unused IP. Since with the bridge setup it has become part of the network connected to the host OS NIC.


If you have any problems with the bridge make sure you read /var/log/messages that might give you a clue to any problems. Of course read any documentation which comes with the software. If it's a package then you might find docs in /usr/share/doc/[package-name]. Also check man pages. For example man qemu. If you have installed your own compiled verion the man pages will be installed into /usr/local/man. Read the user docs on the QEMU website. And of course there's always Google.

Dan Walrond