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 24A distribution will generally provide specific helper scripts when it 25packages QEMU. By default these are found at ``/etc/qemu-ifup`` and 26``/etc/qemu-ifdown`` and are called appropriately when QEMU wants to 27change the network state. 28 29If QEMU is being run as a non-privileged user you may need properly 30configure ``sudo`` so that network commands in the scripts can be 31executed as root. 32 33You must verify that your host kernel supports the TAP network 34interfaces: the device ``/dev/net/tun`` must be present. 35 36See :ref:`sec_005finvocation` to have examples of command 37lines using the TAP network interfaces. 38 39Windows host 40^^^^^^^^^^^^ 41 42There is a virtual ethernet driver for Windows 2000/XP systems, called 43TAP-Win32. But it is not included in standard QEMU for Windows, so you 44will need to get it separately. It is part of OpenVPN package, so 45download OpenVPN from : https://openvpn.net/. 46 47Using the user mode network stack 48~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 49 50By using the option ``-net user`` (default configuration if no ``-net`` 51option is specified), QEMU uses a completely user mode network stack 52(you don't need root privilege to use the virtual network). The virtual 53network configuration is the following:: 54 55 guest (10.0.2.15) <------> Firewall/DHCP server <-----> Internet 56 | (10.0.2.2) 57 | 58 ----> DNS server (10.0.2.3) 59 | 60 ----> SMB server (10.0.2.4) 61 62The QEMU VM behaves as if it was behind a firewall which blocks all 63incoming connections. You can use a DHCP client to automatically 64configure the network in the QEMU VM. The DHCP server assign addresses 65to the hosts starting from 10.0.2.15. 66 67In order to check that the user mode network is working, you can ping 68the address 10.0.2.2 and verify that you got an address in the range 6910.0.2.x from the QEMU virtual DHCP server. 70 71Note that ICMP traffic in general does not work with user mode 72networking. ``ping``, aka. ICMP echo, to the local router (10.0.2.2) 73shall work, however. If you're using QEMU on Linux >= 3.0, it can use 74unprivileged ICMP ping sockets to allow ``ping`` to the Internet. The 75host admin has to set the ping_group_range in order to grant access to 76those sockets. To allow ping for GID 100 (usually users group):: 77 78 echo 100 100 > /proc/sys/net/ipv4/ping_group_range 79 80When using the built-in TFTP server, the router is also the TFTP server. 81 82When using the ``'-netdev user,hostfwd=...'`` option, TCP or UDP 83connections can be redirected from the host to the guest. It allows for 84example to redirect X11, telnet or SSH connections. 85 86Using passt as the user mode network stack 87~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 88 89passt_ can be used as a simple replacement for SLIRP (``-net user``). 90passt doesn't require any capability or privilege. passt has 91better performance than ``-net user``, full IPv6 support and better security 92as it's a daemon that is not executed in QEMU context. 93 94passt_ can be used in the same way as the user backend (using ``-net passt``, 95``-netdev passt`` or ``-nic passt``) or it can be launched manually and 96connected to QEMU either by using a socket (``-netdev stream``) or by using 97the vhost-user interface (``-netdev vhost-user``). 98 99Using ``-netdev stream`` or ``-netdev vhost-user`` will allow the user to 100enable functionalities not available through the passt backend interface 101(like migration). 102 103See `passt(1)`_ for more details on passt. 104 105.. _passt: https://passt.top/ 106.. _passt(1): https://passt.top/builds/latest/web/passt.1.html 107 108To use the passt backend interface 109^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 110 111There is no need to start the daemon as QEMU will do it for you. 112 113By default, passt will be started in the socket-based mode. 114 115.. parsed-literal:: 116 |qemu_system| [...OPTIONS...] -nic passt 117 118 (qemu) info network 119 e1000e.0: index=0,type=nic,model=e1000e,macaddr=52:54:00:12:34:56 120 \ #net071: index=0,type=passt,stream,connected to pid 24846 121 122.. parsed-literal:: 123 |qemu_system| [...OPTIONS...] -net nic -net passt,tcp-ports=10001,udp-ports=10001 124 125 (qemu) info network 126 hub 0 127 \ hub0port1: #net136: index=0,type=passt,stream,connected to pid 25204 128 \ hub0port0: e1000e.0: index=0,type=nic,model=e1000e,macaddr=52:54:00:12:34:56 129 130.. parsed-literal:: 131 |qemu_system| [...OPTIONS...] -netdev passt,id=netdev0 -device virtio-net,mac=9a:2b:2c:2d:2e:2f,id=virtio0,netdev=netdev0 132 133 (qemu) info network 134 virtio0: index=0,type=nic,model=virtio-net-pci,macaddr=9a:2b:2c:2d:2e:2f 135 \ netdev0: index=0,type=passt,stream,connected to pid 25428 136 137To use the vhost-based interface, add the ``vhost-user=on`` parameter and 138select the virtio-net device: 139 140.. parsed-literal:: 141 |qemu_system| [...OPTIONS...] -nic passt,model=virtio,vhost-user=on 142 143 (qemu) info network 144 virtio-net-pci.0: index=0,type=nic,model=virtio-net-pci,macaddr=52:54:00:12:34:56 145 \ #net006: index=0,type=passt,vhost-user,connected to pid 25731 146 147To use socket based passt interface: 148^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 149 150Start passt as a daemon:: 151 152 passt --socket ~/passt.socket 153 154If ``--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``, 155...). Then you can connect your QEMU instance to passt: 156 157.. parsed-literal:: 158 |qemu_system| [...OPTIONS...] -device virtio-net-pci,netdev=netdev0 -netdev stream,id=netdev0,server=off,addr.type=unix,addr.path=~/passt.socket 159 160Where ``~/passt.socket`` is the UNIX socket created by passt to 161communicate with QEMU. 162 163To use vhost-based interface: 164^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 165 166Start passt with ``--vhost-user``:: 167 168 passt --vhost-user --socket ~/passt.socket 169 170Then to connect QEMU: 171 172.. parsed-literal:: 173 |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 174 175Where ``$RAMSIZE`` is the memory size of your VM ``-m`` and ``-object memory-backend-memfd,size=`` must match. 176 177Migration of passt: 178^^^^^^^^^^^^^^^^^^^ 179 180When passt is connected to QEMU using the vhost-user interface it can 181be migrated with QEMU and the network connections are not interrupted. 182 183As passt runs with no privileges, it relies on passt-repair to save and 184load the TCP connections state, using the TCP_REPAIR socket option. 185The 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. 186 187Example of migration of a guest on the same host 188________________________________________________ 189 190Before being able to run passt-repair, the CAP_NET_ADMIN capability must be set 191on the file, run as root:: 192 193 setcap cap_net_admin+eip ./passt-repair 194 195Start passt for the source side:: 196 197 passt --vhost-user --socket ~/passt_src.socket --repair-path ~/passt-repair_src.socket 198 199Where ``~/passt-repair_src.socket`` is the UNIX socket created by passt to 200communicate with passt-repair. The default value is the ``--socket`` path 201appended with ``.repair``. 202 203Start passt-repair:: 204 205 passt-repair ~/passt-repair_src.socket 206 207Start source side QEMU with a monitor to be able to send the migrate command: 208 209.. parsed-literal:: 210 |qemu_system| [...OPTIONS...] [...VHOST USER OPTIONS...] -monitor stdio 211 212Start passt for the destination side:: 213 214 passt --vhost-user --socket ~/passt_dst.socket --repair-path ~/passt-repair_dst.socket 215 216Start passt-repair:: 217 218 passt-repair ~/passt-repair_dst.socket 219 220Start QEMU with the ``-incoming`` parameter: 221 222.. parsed-literal:: 223 |qemu_system| [...OPTIONS...] [...VHOST USER OPTIONS...] -incoming tcp:localhost:4444 224 225Then in the source guest monitor the migration can be started:: 226 227 (qemu) migrate tcp:localhost:4444 228 229A 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 230again. 231 232Hubs 233~~~~ 234 235QEMU can simulate several hubs. A hub can be thought of as a virtual 236connection between several network devices. These devices can be for 237example QEMU virtual ethernet cards or virtual Host ethernet devices 238(TAP devices). You can connect guest NICs or host network backends to 239such a hub using the ``-netdev 240hubport`` or ``-nic hubport`` options. The legacy ``-net`` option also 241connects the given device to the emulated hub with ID 0 (i.e. the 242default hub) unless you specify a netdev with ``-net nic,netdev=xxx`` 243here. 244 245Connecting emulated networks between QEMU instances 246~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 247 248Using the ``-netdev socket`` (or ``-nic socket`` or ``-net socket``) 249option, it is possible to create emulated networks that span several 250QEMU instances. See the description of the ``-netdev socket`` option in 251:ref:`sec_005finvocation` to have a basic 252example. 253