]>
Commit | Line | Data |
---|---|---|
f21673c3 | 1 | ====================================== |
9711cd0d | 2 | QEMU virtio-net standby (net_failover) |
f21673c3 | 3 | ====================================== |
9711cd0d JF |
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. |