Documentation/Networking

Network Basics

There are two parts to networking within QEMU:

• the virtual network device that is provided to the guest (e.g. a PCI network card).
• the network backend that interacts with the emulated NIC (e.g. puts packets onto the host's network).

There are a range of options for each part. By default QEMU will create a SLiRP user network backend and an appropriate virtual network device for the guest (eg an E1000 PCI card for most x86 PC guests), as if you had typed -net nic -net user on your command line.

Note - if you specify any networking options on the command line (via -net or -netdev) then QEMU will require you to provide options sufficient to define and connect up both parts. (Forgetting to specify the backend or the network device will give a warning message such as "Warning: netdev mynet0 has no peer", "Warning: vlan 0 is not connected to host network" or "Warning: vlan 0 with no nics"; the VM will then boot but will not have functioning networking.)

Note - if you are using the (default) SLiRP user networking, then ping (ICMP) will not work, though TCP and UDP will. Don't try to use ping to test your QEMU network configuration!

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

Network Backends

How to create a network backend?

There are a number of network backends to choose from depending on your environment. Create a network backend like this:

-netdev TYPE,id=NAME,...

The id option gives the name by which the virtual network device and the network backend are associated with each other. If you want multiple virtual network devices inside the guest they each need their own network backend. The name is used to distinguish backends from each other and must be used even when only one backend is specified.

Network backend types

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.

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
• in general, ICMP traffic does not work (so you cannot use ping within a guest)
• on Linux hosts, ping does work from within the guest, but it needs initial setup by root (once per host) -- see the steps below
• 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 configure User Networking using the -netdev user command line option.

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,id=mynet0,net=192.168.76.0/24,dhcpstart=192.168.76.9

You can isolate the guest from the host (and broader network) using the restrict option. For example -netdev user,id=mynet0,restrict=y or -netdev type=user,id=mynet0,restrict=yes will restrict networking to just the guest and any virtual devices. This can be used to prevent software running inside the guest from phoning home while still providing a network inside the guest. You can selectively override this using hostfwd and guestfwd options.

Enabling ping in the guest, on Linux hosts

• Determine the main group ID (or one supplementary group ID) of the user that will run QEMU with slirp.

• In /etc/sysctl.conf (or whatever is appropriate for your host distro), make sure that the whitespace-separated, inclusive group ID range in the net.ipv4.ping_group_range sysctl includes the above group ID.

For example, as root,

• add a new group called unpriv_ping:

groupadd unpriv_ping

• set this group for a number of users as another supplementary group (note, they will have to re-login):

for U in user1 user2 ... user_n; do
  usermod --append --groups unpriv_ping $U
done

• then set both sides of the inclusive range in the above sysctl to the numeric ID of the new group:

(
  GROUP_ID=$(getent group unpriv_ping | cut -f 3 -d :)
  printf 'net.ipv4.ping_group_range = %u %u\n' $GROUP_ID $GROUP_ID \
    >> /etc/sysctl.conf
)
sysctl -p

Advanced user networking options

The -netdev user parameter has some more useful options:

• The DHCP address and name for the guest can be set with -netdev user,id=n0,host=addr,hostname=name
• You can specify the guest-visible virtual DNS server address with -netdev user,id=n0,dns=addr
• QEMU can simulate a TFTP server with -netdev user,id=n0,tftp=xxx,bootfile=yyy
• To share files between your guest and host, you can use -netdev user,id=n0,smb=dir,smbserver=addr
• To forward host ports to your guest, use -netdev user,id=n0,hostfwd=hostip:hostport-guestip:guestport

For details, please see the QEMU documentation.

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 have root privileges.

-netdev tap,id=mynet0

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 right 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,id=mynet0,listen=:1234
-netdev socket,id=mynet0,connect=:1234

Virtual Network Devices

How to create a 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:

-device TYPE,netdev=NAME

The netdev is the name of a previously defined -netdev. The virtual network device will be associated with this network backend.

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,mac=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. Remember that ? is a shell metacharacter, so you may need to use -device \? on the command-line.

Network Monitoring

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

You can capture network traffic from within QEMU using the filter-dump object, like this:

-netdev user,id=u1 -device e1000,netdev=u1 \
-object filter-dump,id=f1,netdev=u1,file=dump.dat

Once you've shut down QEMU, you can examine the dump.dat file with tools like Wireshark. Please not that network traffic dumping can only work if QEMU has a chance to see the network packets, i.e. this does not work if you use virtio-net with vhost acceleration in the kernel.

Network HOWTOs

How to get SSH access to a guest

A simplest way is to forward a specific host port to guest port 22. It can be done via:

-device e1000,netdev=net0
-netdev user,id=net0,hostfwd=tcp::5555-:22

The first line creates a virtual e1000 network device, while the second line created one user typed backend, forwarding local port 5555 to guest port 22. Then we can do:

 ssh localhost -p 5555

to have SSH access to guest after its network setup (don't forget to turn off firewalls if there is any in the guest or host).

How to use tap with a wireless adapter on the host

See this:

• Use tap with a wireless adapter on the host

How to disable network completely

If you don't specify any network configuration options, then QEMU will create a SLiRP user network backend and an appropriate virtual network device for the guest (eg an E1000 PCI card for most x86 PC guests). If you don't want any networking at all you can suppress this default with:

-net none

The more general option -nodefaults also suppresses the default networking configuration, as well as the creation of several other default devices.

TODO LIST

• Use tap to let guests be visible on the host network
• Pass QEMU a physical card rather than emulation/simulation.

Misc

The legacy -net option

QEMU previously used the -net nic option instead of -device DEVNAME and -net TYPE instead of -netdev TYPE. This is considered obsolete since QEMU 0.12, although it continues to work.

The legacy syntax to create virtual network devices is:

-net nic,model=MODEL

You can use -net nic,model=? to get a list of valid network devices that you can pass to the -net nic option. Note that these model names are different from the -device ? names and are therefore only useful if you are using the -net nic,model=MODEL syntax. [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.]

QEMU "VLANs"

The obsolete -net syntax automatically created an emulated hub (called a QEMU "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, just an isolated network segment. When creating multiple backends using the -net syntax For example:

-net user,vlan=0 -net nic,vlan=0 -net user,vlan=1 -net nic,vlan=1

Guest Hints

Linux

Should work using default network settings.

Mac OS 9

 -netdev user,id=mynet0 -device sungem,netdev=mynet0

Mac OS 10.2

Starting with QEMU 2.11, the SunGEM NIC can be used. Open the System Preferences, go to the Network pane. You should see a dialog box telling you it has found a new network interface card. Click the Ok button. Click the 'Apply Now' Button at the bottom of the window. The fields in the TCP/IP tab should populate.

 -netdev user,id=mynet0 -device sungem,netdev=mynet0

Mac OS 10.4

-usb -netdev user,id=mynet0 -device usb-net,netdev=mynet0

or

 -netdev user,id=mynet0 -device rtl8139,netdev=mynet0

Open System Preferences and go to the Network pane. Select the Ethernet Adapter from the "Show" drop down menu. From the TCP/IP tab, push the Apply Now button at the bottom. This will make the nic work.

Windows XP

-netdev user,id=n0 -device rtl8139,netdev=n0

Windows will automatically detect and use the NIC.