1.. SPDX-License-Identifier: GPL-2.0
2
3============
4NET_FAILOVER
5============
6
7Overview
8========
9
10The net_failover driver provides an automated failover mechanism via APIs
11to create and destroy a failover master netdev and manages a primary and
12standby slave netdevs that get registered via the generic failover
13infrastructure.
14
15The failover netdev acts a master device and controls 2 slave devices. The
16original paravirtual interface is registered as 'standby' slave netdev and
17a passthru/vf device with the same MAC gets registered as 'primary' slave
18netdev. Both 'standby' and 'failover' netdevs are associated with the same
19'pci' device. The user accesses the network interface via 'failover' netdev.
20The 'failover' netdev chooses 'primary' netdev as default for transmits when
21it is available with link up and running.
22
23This can be used by paravirtual drivers to enable an alternate low latency
24datapath. It also enables hypervisor controlled live migration of a VM with
25direct attached VF by failing over to the paravirtual datapath when the VF
26is unplugged.
27
28virtio-net accelerated datapath: STANDBY mode
29=============================================
30
31net_failover enables hypervisor controlled accelerated datapath to virtio-net
32enabled VMs in a transparent manner with no/minimal guest userspace changes.
33
34To support this, the hypervisor needs to enable VIRTIO_NET_F_STANDBY
35feature on the virtio-net interface and assign the same MAC address to both
36virtio-net and VF interfaces.
37
38Here is an example XML snippet that shows such configuration.
39::
40
41  <interface type='network'>
42    <mac address='52:54:00:00:12:53'/>
43    <source network='enp66s0f0_br'/>
44    <target dev='tap01'/>
45    <model type='virtio'/>
46    <driver name='vhost' queues='4'/>
47    <link state='down'/>
48    <address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/>
49  </interface>
50  <interface type='hostdev' managed='yes'>
51    <mac address='52:54:00:00:12:53'/>
52    <source>
53      <address type='pci' domain='0x0000' bus='0x42' slot='0x02' function='0x5'/>
54    </source>
55    <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/>
56  </interface>
57
58Booting a VM with the above configuration will result in the following 3
59netdevs created in the VM.
60::
61
62  4: ens10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
63      link/ether 52:54:00:00:12:53 brd ff:ff:ff:ff:ff:ff
64      inet 192.168.12.53/24 brd 192.168.12.255 scope global dynamic ens10
65         valid_lft 42482sec preferred_lft 42482sec
66      inet6 fe80::97d8:db2:8c10:b6d6/64 scope link
67         valid_lft forever preferred_lft forever
68  5: ens10nsby: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel master ens10 state UP group default qlen 1000
69      link/ether 52:54:00:00:12:53 brd ff:ff:ff:ff:ff:ff
70  7: ens11: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq master ens10 state UP group default qlen 1000
71      link/ether 52:54:00:00:12:53 brd ff:ff:ff:ff:ff:ff
72
73ens10 is the 'failover' master netdev, ens10nsby and ens11 are the slave
74'standby' and 'primary' netdevs respectively.
75
76Live Migration of a VM with SR-IOV VF & virtio-net in STANDBY mode
77==================================================================
78
79net_failover also enables hypervisor controlled live migration to be supported
80with VMs that have direct attached SR-IOV VF devices by automatic failover to
81the paravirtual datapath when the VF is unplugged.
82
83Here is a sample script that shows the steps to initiate live migration on
84the source hypervisor.
85::
86
87  # cat vf_xml
88  <interface type='hostdev' managed='yes'>
89    <mac address='52:54:00:00:12:53'/>
90    <source>
91      <address type='pci' domain='0x0000' bus='0x42' slot='0x02' function='0x5'/>
92    </source>
93    <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/>
94  </interface>
95
96  # Source Hypervisor
97  #!/bin/bash
98
99  DOMAIN=fedora27-tap01
100  PF=enp66s0f0
101  VF_NUM=5
102  TAP_IF=tap01
103  VF_XML=
104
105  MAC=52:54:00:00:12:53
106  ZERO_MAC=00:00:00:00:00:00
107
108  virsh domif-setlink $DOMAIN $TAP_IF up
109  bridge fdb del $MAC dev $PF master
110  virsh detach-device $DOMAIN $VF_XML
111  ip link set $PF vf $VF_NUM mac $ZERO_MAC
112
113  virsh migrate --live $DOMAIN qemu+ssh://$REMOTE_HOST/system
114
115  # Destination Hypervisor
116  #!/bin/bash
117
118  virsh attach-device $DOMAIN $VF_XML
119  virsh domif-setlink $DOMAIN $TAP_IF down
120