1.. _Network_Emulation: 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 80Using passt as the user mode network stack 81~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 82 83passt_ can be used as a simple replacement for SLIRP (``-net user``). 84passt doesn't require any capability or privilege. passt has 85better performance than ``-net user``, full IPv6 support and better security 86as it's a daemon that is not executed in QEMU context. 87 88passt can be connected to QEMU either by using a socket 89(``-netdev stream``) or using the vhost-user interface (``-netdev vhost-user``). 90See `passt(1)`_ for more details on passt. 91 92.. _passt: https://passt.top/ 93.. _passt(1): https://passt.top/builds/latest/web/passt.1.html 94 95To use socket based passt interface: 96^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 97 98Start passt as a daemon:: 99 100 passt --socket ~/passt.socket 101 102If ``--socket`` is not provided, passt will print the path of the UNIX domain socket QEMU can connect to (``/tmp/passt_1.socket``, ``/tmp/passt_2.socket``, 103...). Then you can connect your QEMU instance to passt: 104 105.. parsed-literal:: 106 |qemu_system| [...OPTIONS...] -device virtio-net-pci,netdev=netdev0 -netdev stream,id=netdev0,server=off,addr.type=unix,addr.path=~/passt.socket 107 108Where ``~/passt.socket`` is the UNIX socket created by passt to 109communicate with QEMU. 110 111To use vhost-based interface: 112^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 113 114Start passt with ``--vhost-user``:: 115 116 passt --vhost-user --socket ~/passt.socket 117 118Then to connect QEMU: 119 120.. parsed-literal:: 121 |qemu_system| [...OPTIONS...] -m $RAMSIZE -chardev socket,id=chr0,path=~/passt.socket -netdev vhost-user,id=netdev0,chardev=chr0 -device virtio-net,netdev=netdev0 -object memory-backend-memfd,id=memfd0,share=on,size=$RAMSIZE -numa node,memdev=memfd0 122 123Where ``$RAMSIZE`` is the memory size of your VM ``-m`` and ``-object memory-backend-memfd,size=`` must match. 124 125Migration of passt: 126^^^^^^^^^^^^^^^^^^^ 127 128When passt is connected to QEMU using the vhost-user interface it can 129be migrated with QEMU and the network connections are not interrupted. 130 131As passt runs with no privileges, it relies on passt-repair to save and 132load the TCP connections state, using the TCP_REPAIR socket option. 133The passt-repair helper needs to have the CAP_NET_ADMIN capability, or run as root. If passt-repair is not available, TCP connections will not be preserved. 134 135Example of migration of a guest on the same host 136________________________________________________ 137 138Before being able to run passt-repair, the CAP_NET_ADMIN capability must be set 139on the file, run as root:: 140 141 setcap cap_net_admin+eip ./passt-repair 142 143Start passt for the source side:: 144 145 passt --vhost-user --socket ~/passt_src.socket --repair-path ~/passt-repair_src.socket 146 147Where ``~/passt-repair_src.socket`` is the UNIX socket created by passt to 148communicate with passt-repair. The default value is the ``--socket`` path 149appended with ``.repair``. 150 151Start passt-repair:: 152 153 passt-repair ~/passt-repair_src.socket 154 155Start source side QEMU with a monitor to be able to send the migrate command: 156 157.. parsed-literal:: 158 |qemu_system| [...OPTIONS...] [...VHOST USER OPTIONS...] -monitor stdio 159 160Start passt for the destination side:: 161 162 passt --vhost-user --socket ~/passt_dst.socket --repair-path ~/passt-repair_dst.socket 163 164Start passt-repair:: 165 166 passt-repair ~/passt-repair_dst.socket 167 168Start QEMU with the ``-incoming`` parameter: 169 170.. parsed-literal:: 171 |qemu_system| [...OPTIONS...] [...VHOST USER OPTIONS...] -incoming tcp:localhost:4444 172 173Then in the source guest monitor the migration can be started:: 174 175 (qemu) migrate tcp:localhost:4444 176 177A separate passt-repair instance must be started for every migration. In the case of a failed migration, passt-repair also needs to be restarted before trying 178again. 179 180Hubs 181~~~~ 182 183QEMU can simulate several hubs. A hub can be thought of as a virtual 184connection between several network devices. These devices can be for 185example QEMU virtual ethernet cards or virtual Host ethernet devices 186(TAP devices). You can connect guest NICs or host network backends to 187such a hub using the ``-netdev 188hubport`` or ``-nic hubport`` options. The legacy ``-net`` option also 189connects the given device to the emulated hub with ID 0 (i.e. the 190default hub) unless you specify a netdev with ``-net nic,netdev=xxx`` 191here. 192 193Connecting emulated networks between QEMU instances 194~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 195 196Using the ``-netdev socket`` (or ``-nic socket`` or ``-net socket``) 197option, it is possible to create emulated networks that span several 198QEMU instances. See the description of the ``-netdev socket`` option in 199:ref:`sec_005finvocation` to have a basic 200example. 201