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