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