| 1 | ====================================== |
| 2 | QEMU virtio-net standby (net_failover) |
| 3 | ====================================== |
| 4 | |
| 5 | This document explains the setup and usage of virtio-net standby feature which |
| 6 | is used to create a net_failover pair of devices. |
| 7 | |
| 8 | The general idea is that we have a pair of devices, a (vfio-)pci and a |
| 9 | virtio-net device. Before migration the vfio device is unplugged and data flows |
| 10 | through the virtio-net device, on the target side another vfio-pci device is |
| 11 | plugged in to take over the data-path. In the guest the net_failover kernel |
| 12 | module will pair net devices with the same MAC address. |
| 13 | |
| 14 | The two devices are called primary and standby device. The fast hardware based |
| 15 | networking device is called the primary device and the virtio-net device is the |
| 16 | standby device. |
| 17 | |
| 18 | Restrictions |
| 19 | ------------ |
| 20 | |
| 21 | Currently only PCIe devices are allowed as primary devices, this restriction |
| 22 | can be lifted in the future with enhanced QEMU support. Also, only networking |
| 23 | devices are allowed as primary device. The user needs to ensure that primary |
| 24 | and standby devices are not plugged into the same PCIe slot. |
| 25 | |
| 26 | Usecase |
| 27 | ------- |
| 28 | |
| 29 | Virtio-net standby allows easy migration while using a passed-through |
| 30 | fast networking device by falling back to a virtio-net device for the |
| 31 | duration of the migration. It is like a simple version of a bond, the |
| 32 | difference is that it requires no configuration in the guest. When a |
| 33 | guest is live-migrated to another host QEMU will unplug the primary |
| 34 | device via the PCIe based hotplug handler and traffic will go through |
| 35 | the virtio-net device. On the target system the primary device will be |
| 36 | automatically plugged back and the net_failover module registers it |
| 37 | again as the primary device. |
| 38 | |
| 39 | Usage |
| 40 | ----- |
| 41 | |
| 42 | The primary device can be hotplugged or be part of the startup configuration |
| 43 | |
| 44 | .. code-block:: shell |
| 45 | |
| 46 | -device virtio-net-pci,netdev=hostnet1,id=net1,mac=52:54:00:6f:55:cc,bus=root2,failover=on |
| 47 | |
| 48 | With the parameter ``failover=on`` the VIRTIO_NET_F_STANDBY feature will be enabled. |
| 49 | |
| 50 | .. code-block:: shell |
| 51 | |
| 52 | -device vfio-pci,host=5e:00.2,id=hostdev0,bus=root1,failover_pair_id=net1 |
| 53 | |
| 54 | ``failover_pair_id`` references the id of the virtio-net standby device. |
| 55 | This is only for pairing the devices within QEMU. The guest kernel |
| 56 | module net_failover will match devices with identical MAC addresses. |
| 57 | |
| 58 | Hotplug |
| 59 | ------- |
| 60 | |
| 61 | Both primary and standby device can be hotplugged via the QEMU |
| 62 | monitor. Note that if the virtio-net device is plugged first a warning |
| 63 | will be issued that it couldn't find the primary device. |
| 64 | |
| 65 | Migration |
| 66 | --------- |
| 67 | |
| 68 | A new migration state wait-unplug was added for this feature. If |
| 69 | failover primary devices are present in the configuration, migration |
| 70 | will go into this state. It will wait until the device unplug is |
| 71 | completed in the guest and then move into active state. On the target |
| 72 | system the primary devices will be automatically hotplugged when the |
| 73 | feature bit was negotiated for the virtio-net standby device. |