Documentation/Networking

There are two parts to networking within QEMU:

• the virtual network device that is provided to the network card (e.g. an emulation of PCI network card)
• the network backend that takes the results of that emulated card and does some networking operation (e.g. puts it onto a real network).

There are a range of options for each part.

Note - As this page is probably very brief or even incomplete you might find these pages rather useful:

• QEMU Networking on wikibooks.org, mainly dealing with Linux hosts
• QEMU Networking on bsdwiki, showing used networking principles and dealing with BSD hosts

Virtual Network Device

The virtual network device that you choose depends on your needs and the guest environment (i.e. the hardware that you are emulating). For example, if you are emulating a particular embedded board, then you should use the virtual network device that matches that embedded board's configuration.

On machines that have PCI bus, there are a wider range of options. The e1000 is the default network adapter in qemu. The rtl8139 is the default network adapter in qemu-kvm. In both projects, the virtio-net (para-virtualised) network adapter has the best performance, but requires special guest driver support.

Use the -device option to add a particular virtual network device to your virtual machine. QEMU previously used the -net nic option - this is now considered obsolete, although it continues to work.

Note that there are other device options to select alternative devices, or to change some aspect of the device. For example, you want something like: -device DEVNAME,netdev=NET-ID,macaddr=MACADDR,DEV-OPTS, where DEVNAME is the device (e.g. i82559c for an Intel i82559C Ethernet device), NET_ID is the network identifier to attach the device to (see discussion of -netdev below), MACADDR is the MAC address for the device, and DEV-OPTS are any additional device options that you may wish to pass (e.g. bus=PCI-BUS,addr=DEVFN to control the PCI device address), if supported by the device.

Use -device ? to get a list of the devices (including network devices) you can add using the -device option for a particular guest.

You can also use -net nic,model=? to get a list of valid network devices that you can pass to the -net nic option. [If you'd like to know all of the virtual network devices that are currently provided in QEMU, a search for "NetClientInfo" in the source code may be useful.]

See the qemu man page for the various options that you can pass to -net nic.

Creating a network backend

There are two ways to create a network backend. The -netdev syntax (introduced in QEMU 0.12.0) is the preferred way to create a network backend. The obsolete -net syntax also creates a network backend in additional to a QEMU VLAN.

In most cases, if you don't have any specific networking requirements other than to be able to access to a web page from your guest, user networking (slirp) is a good choice. However, if you are looking to run any kind of network service or have your guest participate in a network in any meaningful way, tap is usually the best choice.

QEMU VLANs. The obsolete -net syntax automatically created an emulated hub (called a VLAN, for virtual LAN) that forwards traffic from any device connected to it to every other device on the VLAN. It is not an 802.1q VLAN. When creating multiple network devices using the -net syntax, you generally want to specify different vlan ids. The exception is when dealing with the socket backend.

Choosing which networking backend to use

User Networking (SLIRP)

This is the default networking backend and generally is the easiest to use. It does not require root / Administrator privileges. It has the following limitations:

• there is a lot of overhead so the performance is poor
• ICMP traffic does not work (so you cannot use ping within a guest)
• the guest is not directly accessible from the host or the external network

User Networking is implemented using "slirp", which provides a full TCP/IP stack within QEMU and uses that stack to implement a virtual NAT'd network.

A typical (default) network is shown below.

You can change the network configuration using the -netdev type=user command line option (-netdev user is an equivalent shortcut, but the user part must be the first option if you are using this shortcut). Note that this was previously controlled using the -net user command line option, and while this continues to work, it is considered obsolete. Refer to the qemu manual page for more information on -net user.

There are some important options.

The id option can be used with the -device to "plug" a particular network device into the network backend. For example, something like -netdev type=user,id=mynet0 -device e1000,netdev=mynet0

Adding the following to the qemu command line will change the network configuration to use 192.168.76.0/24 instead of the default (10.0.2.0/24) and will start guest DHCP allocation from 9 (instead of 15): -netdev user,net=192.168.76.0/24,dhcpstart=192.168.76.9.

TODO: -netdev user,dns=xxx

-netdev user,tftp=xxx,bootfile=yyy

-netdev user,smb=xxx,smbserver=yyy

-netdev user,hostfwd=hostip:hostport-guestip:guestport

-netdev user,guestfwd=

-netdev user,restrict=y

-netdev host=xxx,hostname=yyy

Tap

The tap networking backend makes use of a tap networking device in the host. It offers very good performance and can be configured to create virtually any type of network topology. Unfortunately, it requires configuration of that network topology in the host which tends to be different depending on the operating system you are using. Generally speaking, it also requires that you invoke QEMU as root.

-netdev tap

VDE

The VDE networking backend uses the Virtual Distributed Ethernet infrastructure to network guests. Unless you specifically know that you want to use VDE, it is probably not the best backend to use.

Socket

The socket networking backend, together with QEMU VLANs, allow you to create a network of guests that can see each other. It's primarily useful in extending the network created by Documentation/Networking/Slirp to multiple virtual machines. In general, if you want to have multiple guests communicate, tap is a better choice unless you do not have root access to the host environment.

-netdev socket

Monitoring Networking

You can monitor the network configuration using info network and info usernet commands.

You can capture network traffic from within qemu using the -net dump command line option. See Stefan Hajnoczi's blog post on this feature.

How do I...

• Use tap to let guests be visible on the host network
• Use tap with a wireless adapter on the host
• Forward ports with slirp
• Pass QEMU a physical card rather than emulation/simulation.