docs/system/virtio-net-failover.rst

2 QEMU virtio-net standby (net_failover)
5 This document explains the setup and usage of virtio-net standby feature which
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.
15 networking device is called the primary device and the virtio-net device is the
19 ------------
21 Currently only PCIe devices are allowed as primary devices, this restriction
24 and standby devices are not plugged into the same PCIe slot.
27 -------
29   Virtio-net standby allows easy migration while using a passed-through fast
30   networking device by falling back to a virtio-net device for the duration of
32   requires no configuration in the guest. When a guest is live-migrated to
33   another host QEMU will unplug the primary device via the PCIe based hotplug
34   handler and traffic will go through the virtio-net device.  On the target
39 -----
43   -device virtio-net-pci,netdev=hostnet1,id=net1,mac=52:54:00:6f:55:cc, \
48   -device vfio-pci,host=5e:00.2,id=hostdev0,bus=root1,failover_pair_id=net1
50   failover_pair_id references the id of the virtio-net standby device. This
52   net_failover will match devices with identical MAC addresses.
55 -------
58   that if the virtio-net device is plugged first a warning will be issued that it
62 ---------
64   A new migration state wait-unplug was added for this feature. If failover primary
68   when the feature bit was negotiated for the virtio-net standby device.