docs/virtio-net-failover.rst

   1 ========================
   2 QEMU virtio-net standby (net_failover)
   3 ========================
   4
   5 This document explains the setup and usage of virtio-net standby feature which
   6 is used to create a net_failover pair of devices.
   7
   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.
  13
  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.
  17
  18 Restrictions
  19 ------------
  20
  21 Currently only PCIe devices are allowed as primary devices, this restriction
  22 can be lifted in the future with enhanced QEMU support. Also, only networking
  23 devices are allowed as primary device. The user needs to ensure that primary
  24 and standby devices are not plugged into the same PCIe slot.
  25
  26 Usecase
  27 -------
  28
  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
  31   the migration. It is like a simple version of a bond, the difference is that it
  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.
  37
  38 Usage
  39 -----
  40
  41   The primary device can be hotplugged or be part of the startup configuration
  42
  43   -device virtio-net-pci,netdev=hostnet1,id=net1,mac=52:54:00:6f:55:cc, \
  44     bus=root2,failover=on
  45
  46   With the parameter failover=on the VIRTIO_NET_F_STANDBY feature will be enabled.
  47
  48   -device vfio-pci,host=5e:00.2,id=hostdev0,bus=root1,failover_pair_id=net1
  49
  50   failover_pair_id references the id of the virtio-net standby device. This
  51   is only for pairing the devices within QEMU. The guest kernel module
  52   net_failover will match devices with identical MAC addresses.
  53
  54 Hotplug
  55 -------
  56
  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.
  60
  61 Migration
  62 ---------
  63
  64   A new migration state wait-unplug was added for this feature. If failover primary
  65   devices are present in the configuration, migration will go into this state.
  66   It will wait until the device unplug is completed in the guest and then move into
  67   active state. On the target system the primary devices will be automatically hotplugged
  68   when the feature bit was negotiated for the virtio-net standby device.