docs/system/net.rst

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