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