1.. _pcsys_005fnetwork:
2
3Network emulation
4-----------------
5
6QEMU can simulate several network cards (e.g. PCI or ISA cards on the PC
7target) and can connect them to a network backend on the host or an
8emulated hub. The various host network backends can either be used to
9connect the NIC of the guest to a real network (e.g. by using a TAP
10devices or the non-privileged user mode network stack), or to other
11guest instances running in another QEMU process (e.g. by using the
12socket host network backend).
13
14Using TAP network interfaces
15~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16
17This is the standard way to connect QEMU to a real network. QEMU adds a
18virtual network device on your host (called ``tapN``), and you can then
19configure it as if it was a real ethernet card.
20
21Linux host
22^^^^^^^^^^
23
24As an example, you can download the ``linux-test-xxx.tar.gz`` archive
25and copy the script ``qemu-ifup`` in ``/etc`` and configure properly
26``sudo`` so that the command ``ifconfig`` contained in ``qemu-ifup`` can
27be executed as root. You must verify that your host kernel supports the
28TAP network interfaces: the device ``/dev/net/tun`` must be present.
29
30See :ref:`sec_005finvocation` to have examples of command
31lines using the TAP network interfaces.
32
33Windows host
34^^^^^^^^^^^^
35
36There is a virtual ethernet driver for Windows 2000/XP systems, called
37TAP-Win32. But it is not included in standard QEMU for Windows, so you
38will need to get it separately. It is part of OpenVPN package, so
39download OpenVPN from : https://openvpn.net/.
40
41Using the user mode network stack
42~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43
44By using the option ``-net user`` (default configuration if no ``-net``
45option is specified), QEMU uses a completely user mode network stack
46(you don't need root privilege to use the virtual network). The virtual
47network configuration is the following::
48
49        guest (10.0.2.15)  <------>  Firewall/DHCP server <-----> Internet
50                              |          (10.0.2.2)
51                              |
52                              ---->  DNS server (10.0.2.3)
53                              |
54                              ---->  SMB server (10.0.2.4)
55
56The QEMU VM behaves as if it was behind a firewall which blocks all
57incoming connections. You can use a DHCP client to automatically
58configure the network in the QEMU VM. The DHCP server assign addresses
59to the hosts starting from 10.0.2.15.
60
61In order to check that the user mode network is working, you can ping
62the address 10.0.2.2 and verify that you got an address in the range
6310.0.2.x from the QEMU virtual DHCP server.
64
65Note that ICMP traffic in general does not work with user mode
66networking. ``ping``, aka. ICMP echo, to the local router (10.0.2.2)
67shall work, however. If you're using QEMU on Linux >= 3.0, it can use
68unprivileged ICMP ping sockets to allow ``ping`` to the Internet. The
69host admin has to set the ping_group_range in order to grant access to
70those sockets. To allow ping for GID 100 (usually users group)::
71
72   echo 100 100 > /proc/sys/net/ipv4/ping_group_range
73
74When using the built-in TFTP server, the router is also the TFTP server.
75
76When using the ``'-netdev user,hostfwd=...'`` option, TCP or UDP
77connections can be redirected from the host to the guest. It allows for
78example to redirect X11, telnet or SSH connections.
79
80Hubs
81~~~~
82
83QEMU can simulate several hubs. A hub can be thought of as a virtual
84connection between several network devices. These devices can be for
85example QEMU virtual ethernet cards or virtual Host ethernet devices
86(TAP devices). You can connect guest NICs or host network backends to
87such a hub using the ``-netdev
88hubport`` or ``-nic hubport`` options. The legacy ``-net`` option also
89connects the given device to the emulated hub with ID 0 (i.e. the
90default hub) unless you specify a netdev with ``-net nic,netdev=xxx``
91here.
92
93Connecting emulated networks between QEMU instances
94~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
95
96Using the ``-netdev socket`` (or ``-nic socket`` or ``-net socket``)
97option, it is possible to create emulated networks that span several
98QEMU instances. See the description of the ``-netdev socket`` option in
99:ref:`sec_005finvocation` to have a basic
100example.
101