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
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.
19 ------------
23 devices are allowed as primary device. The user needs to ensure that primary
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
35   system the primary device will be automatically plugged back and the
36   net_failover module registers it again as the primary device.
39 -----
41   The primary device can be hotplugged or be part of the startup configuration
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
55 -------
57   Both primary and standby device can be hotplugged via the QEMU monitor.  Note
58   that if the virtio-net device is plugged first a warning will be issued that it
59   couldn't find the primary device.
62 ---------
64   A new migration state wait-unplug was added for this feature. If failover primary
66   It will wait until the device unplug is completed in the guest and then move into
68   when the feature bit was negotiated for the virtio-net standby device.