1*f21673c3SStefan Hajnoczi====================================== 29711cd0dSJens FreimannQEMU virtio-net standby (net_failover) 3*f21673c3SStefan Hajnoczi====================================== 49711cd0dSJens Freimann 59711cd0dSJens FreimannThis document explains the setup and usage of virtio-net standby feature which 69711cd0dSJens Freimannis used to create a net_failover pair of devices. 79711cd0dSJens Freimann 89711cd0dSJens FreimannThe general idea is that we have a pair of devices, a (vfio-)pci and a 99711cd0dSJens Freimannvirtio-net device. Before migration the vfio device is unplugged and data flows 109711cd0dSJens Freimannthrough the virtio-net device, on the target side another vfio-pci device is 119711cd0dSJens Freimannplugged in to take over the data-path. In the guest the net_failover kernel 129711cd0dSJens Freimannmodule will pair net devices with the same MAC address. 139711cd0dSJens Freimann 149711cd0dSJens FreimannThe two devices are called primary and standby device. The fast hardware based 159711cd0dSJens Freimannnetworking device is called the primary device and the virtio-net device is the 169711cd0dSJens Freimannstandby device. 179711cd0dSJens Freimann 189711cd0dSJens FreimannRestrictions 199711cd0dSJens Freimann------------ 209711cd0dSJens Freimann 219711cd0dSJens FreimannCurrently only PCIe devices are allowed as primary devices, this restriction 229711cd0dSJens Freimanncan be lifted in the future with enhanced QEMU support. Also, only networking 239711cd0dSJens Freimanndevices are allowed as primary device. The user needs to ensure that primary 249711cd0dSJens Freimannand standby devices are not plugged into the same PCIe slot. 259711cd0dSJens Freimann 269711cd0dSJens FreimannUsecase 279711cd0dSJens Freimann------- 289711cd0dSJens Freimann 299711cd0dSJens Freimann Virtio-net standby allows easy migration while using a passed-through fast 309711cd0dSJens Freimann networking device by falling back to a virtio-net device for the duration of 319711cd0dSJens Freimann the migration. It is like a simple version of a bond, the difference is that it 329711cd0dSJens Freimann requires no configuration in the guest. When a guest is live-migrated to 339711cd0dSJens Freimann another host QEMU will unplug the primary device via the PCIe based hotplug 349711cd0dSJens Freimann handler and traffic will go through the virtio-net device. On the target 359711cd0dSJens Freimann system the primary device will be automatically plugged back and the 369711cd0dSJens Freimann net_failover module registers it again as the primary device. 379711cd0dSJens Freimann 389711cd0dSJens FreimannUsage 399711cd0dSJens Freimann----- 409711cd0dSJens Freimann 419711cd0dSJens Freimann The primary device can be hotplugged or be part of the startup configuration 429711cd0dSJens Freimann 439711cd0dSJens Freimann -device virtio-net-pci,netdev=hostnet1,id=net1,mac=52:54:00:6f:55:cc, \ 449711cd0dSJens Freimann bus=root2,failover=on 459711cd0dSJens Freimann 469711cd0dSJens Freimann With the parameter failover=on the VIRTIO_NET_F_STANDBY feature will be enabled. 479711cd0dSJens Freimann 489711cd0dSJens Freimann -device vfio-pci,host=5e:00.2,id=hostdev0,bus=root1,failover_pair_id=net1 499711cd0dSJens Freimann 509711cd0dSJens Freimann failover_pair_id references the id of the virtio-net standby device. This 519711cd0dSJens Freimann is only for pairing the devices within QEMU. The guest kernel module 529711cd0dSJens Freimann net_failover will match devices with identical MAC addresses. 539711cd0dSJens Freimann 549711cd0dSJens FreimannHotplug 559711cd0dSJens Freimann------- 569711cd0dSJens Freimann 579711cd0dSJens Freimann Both primary and standby device can be hotplugged via the QEMU monitor. Note 589711cd0dSJens Freimann that if the virtio-net device is plugged first a warning will be issued that it 599711cd0dSJens Freimann couldn't find the primary device. 609711cd0dSJens Freimann 619711cd0dSJens FreimannMigration 629711cd0dSJens Freimann--------- 639711cd0dSJens Freimann 649711cd0dSJens Freimann A new migration state wait-unplug was added for this feature. If failover primary 659711cd0dSJens Freimann devices are present in the configuration, migration will go into this state. 669711cd0dSJens Freimann It will wait until the device unplug is completed in the guest and then move into 679711cd0dSJens Freimann active state. On the target system the primary devices will be automatically hotplugged 689711cd0dSJens Freimann when the feature bit was negotiated for the virtio-net standby device. 69