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 used in the same way as the user backend (using ``-net passt``, 89``-netdev passt`` or ``-nic passt``) or it can be launched manually and 90connected to QEMU either by using a socket (``-netdev stream``) or by using 91the vhost-user interface (``-netdev vhost-user``). 92 93Using ``-netdev stream`` or ``-netdev vhost-user`` will allow the user to 94enable functionalities not available through the passt backend interface 95(like migration). 96 97See `passt(1)`_ for more details on passt. 98 99.. _passt: https://passt.top/ 100.. _passt(1): https://passt.top/builds/latest/web/passt.1.html 101 102To use the passt backend interface 103^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 104 105There is no need to start the daemon as QEMU will do it for you. 106 107passt is started in the socket-based mode. 108 109.. parsed-literal:: 110 |qemu_system| [...OPTIONS...] -nic passt 111 112 (qemu) info network 113 e1000e.0: index=0,type=nic,model=e1000e,macaddr=52:54:00:12:34:56 114 \ #net071: index=0,type=passt,stream,connected to pid 24846 115 116.. parsed-literal:: 117 |qemu_system| [...OPTIONS...] -net nic -net passt,tcp-ports=10001,udp-ports=10001 118 119 (qemu) info network 120 hub 0 121 \ hub0port1: #net136: index=0,type=passt,stream,connected to pid 25204 122 \ hub0port0: e1000e.0: index=0,type=nic,model=e1000e,macaddr=52:54:00:12:34:56 123 124.. parsed-literal:: 125 |qemu_system| [...OPTIONS...] -netdev passt,id=netdev0 -device virtio-net,mac=9a:2b:2c:2d:2e:2f,id=virtio0,netdev=netdev0 126 127 (qemu) info network 128 virtio0: index=0,type=nic,model=virtio-net-pci,macaddr=9a:2b:2c:2d:2e:2f 129 \ netdev0: index=0,type=passt,stream,connected to pid 25428 130 131To use socket based passt interface: 132^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 133 134Start passt as a daemon:: 135 136 passt --socket ~/passt.socket 137 138If ``--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``, 139...). Then you can connect your QEMU instance to passt: 140 141.. parsed-literal:: 142 |qemu_system| [...OPTIONS...] -device virtio-net-pci,netdev=netdev0 -netdev stream,id=netdev0,server=off,addr.type=unix,addr.path=~/passt.socket 143 144Where ``~/passt.socket`` is the UNIX socket created by passt to 145communicate with QEMU. 146 147To use vhost-based interface: 148^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 149 150Start passt with ``--vhost-user``:: 151 152 passt --vhost-user --socket ~/passt.socket 153 154Then to connect QEMU: 155 156.. parsed-literal:: 157 |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 158 159Where ``$RAMSIZE`` is the memory size of your VM ``-m`` and ``-object memory-backend-memfd,size=`` must match. 160 161Migration of passt: 162^^^^^^^^^^^^^^^^^^^ 163 164When passt is connected to QEMU using the vhost-user interface it can 165be migrated with QEMU and the network connections are not interrupted. 166 167As passt runs with no privileges, it relies on passt-repair to save and 168load the TCP connections state, using the TCP_REPAIR socket option. 169The 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. 170 171Example of migration of a guest on the same host 172________________________________________________ 173 174Before being able to run passt-repair, the CAP_NET_ADMIN capability must be set 175on the file, run as root:: 176 177 setcap cap_net_admin+eip ./passt-repair 178 179Start passt for the source side:: 180 181 passt --vhost-user --socket ~/passt_src.socket --repair-path ~/passt-repair_src.socket 182 183Where ``~/passt-repair_src.socket`` is the UNIX socket created by passt to 184communicate with passt-repair. The default value is the ``--socket`` path 185appended with ``.repair``. 186 187Start passt-repair:: 188 189 passt-repair ~/passt-repair_src.socket 190 191Start source side QEMU with a monitor to be able to send the migrate command: 192 193.. parsed-literal:: 194 |qemu_system| [...OPTIONS...] [...VHOST USER OPTIONS...] -monitor stdio 195 196Start passt for the destination side:: 197 198 passt --vhost-user --socket ~/passt_dst.socket --repair-path ~/passt-repair_dst.socket 199 200Start passt-repair:: 201 202 passt-repair ~/passt-repair_dst.socket 203 204Start QEMU with the ``-incoming`` parameter: 205 206.. parsed-literal:: 207 |qemu_system| [...OPTIONS...] [...VHOST USER OPTIONS...] -incoming tcp:localhost:4444 208 209Then in the source guest monitor the migration can be started:: 210 211 (qemu) migrate tcp:localhost:4444 212 213A 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 214again. 215 216Hubs 217~~~~ 218 219QEMU can simulate several hubs. A hub can be thought of as a virtual 220connection between several network devices. These devices can be for 221example QEMU virtual ethernet cards or virtual Host ethernet devices 222(TAP devices). You can connect guest NICs or host network backends to 223such a hub using the ``-netdev 224hubport`` or ``-nic hubport`` options. The legacy ``-net`` option also 225connects the given device to the emulated hub with ID 0 (i.e. the 226default hub) unless you specify a netdev with ``-net nic,netdev=xxx`` 227here. 228 229Connecting emulated networks between QEMU instances 230~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 231 232Using the ``-netdev socket`` (or ``-nic socket`` or ``-net socket``) 233option, it is possible to create emulated networks that span several 234QEMU instances. See the description of the ``-netdev socket`` option in 235:ref:`sec_005finvocation` to have a basic 236example. 237