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 107By default, passt will be 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 the vhost-based interface, add the ``vhost-user=on`` parameter and 132select the virtio-net device: 133 134.. parsed-literal:: 135 |qemu_system| [...OPTIONS...] -nic passt,model=virtio,vhost-user=on 136 137 (qemu) info network 138 virtio-net-pci.0: index=0,type=nic,model=virtio-net-pci,macaddr=52:54:00:12:34:56 139 \ #net006: index=0,type=passt,vhost-user,connected to pid 25731 140 141To use socket based passt interface: 142^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 143 144Start passt as a daemon:: 145 146 passt --socket ~/passt.socket 147 148If ``--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``, 149...). Then you can connect your QEMU instance to passt: 150 151.. parsed-literal:: 152 |qemu_system| [...OPTIONS...] -device virtio-net-pci,netdev=netdev0 -netdev stream,id=netdev0,server=off,addr.type=unix,addr.path=~/passt.socket 153 154Where ``~/passt.socket`` is the UNIX socket created by passt to 155communicate with QEMU. 156 157To use vhost-based interface: 158^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 159 160Start passt with ``--vhost-user``:: 161 162 passt --vhost-user --socket ~/passt.socket 163 164Then to connect QEMU: 165 166.. parsed-literal:: 167 |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 168 169Where ``$RAMSIZE`` is the memory size of your VM ``-m`` and ``-object memory-backend-memfd,size=`` must match. 170 171Migration of passt: 172^^^^^^^^^^^^^^^^^^^ 173 174When passt is connected to QEMU using the vhost-user interface it can 175be migrated with QEMU and the network connections are not interrupted. 176 177As passt runs with no privileges, it relies on passt-repair to save and 178load the TCP connections state, using the TCP_REPAIR socket option. 179The 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. 180 181Example of migration of a guest on the same host 182________________________________________________ 183 184Before being able to run passt-repair, the CAP_NET_ADMIN capability must be set 185on the file, run as root:: 186 187 setcap cap_net_admin+eip ./passt-repair 188 189Start passt for the source side:: 190 191 passt --vhost-user --socket ~/passt_src.socket --repair-path ~/passt-repair_src.socket 192 193Where ``~/passt-repair_src.socket`` is the UNIX socket created by passt to 194communicate with passt-repair. The default value is the ``--socket`` path 195appended with ``.repair``. 196 197Start passt-repair:: 198 199 passt-repair ~/passt-repair_src.socket 200 201Start source side QEMU with a monitor to be able to send the migrate command: 202 203.. parsed-literal:: 204 |qemu_system| [...OPTIONS...] [...VHOST USER OPTIONS...] -monitor stdio 205 206Start passt for the destination side:: 207 208 passt --vhost-user --socket ~/passt_dst.socket --repair-path ~/passt-repair_dst.socket 209 210Start passt-repair:: 211 212 passt-repair ~/passt-repair_dst.socket 213 214Start QEMU with the ``-incoming`` parameter: 215 216.. parsed-literal:: 217 |qemu_system| [...OPTIONS...] [...VHOST USER OPTIONS...] -incoming tcp:localhost:4444 218 219Then in the source guest monitor the migration can be started:: 220 221 (qemu) migrate tcp:localhost:4444 222 223A 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 224again. 225 226Hubs 227~~~~ 228 229QEMU can simulate several hubs. A hub can be thought of as a virtual 230connection between several network devices. These devices can be for 231example QEMU virtual ethernet cards or virtual Host ethernet devices 232(TAP devices). You can connect guest NICs or host network backends to 233such a hub using the ``-netdev 234hubport`` or ``-nic hubport`` options. The legacy ``-net`` option also 235connects the given device to the emulated hub with ID 0 (i.e. the 236default hub) unless you specify a netdev with ``-net nic,netdev=xxx`` 237here. 238 239Connecting emulated networks between QEMU instances 240~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 241 242Using the ``-netdev socket`` (or ``-nic socket`` or ``-net socket``) 243option, it is possible to create emulated networks that span several 244QEMU instances. See the description of the ``-netdev socket`` option in 245:ref:`sec_005finvocation` to have a basic 246example. 247