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 mananges a primary and
12standby slave netdevs that get registered via the generic failover
13infrastructrure.
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 chanages.
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 <interface type='network'>
41   <mac address='52:54:00:00:12:53'/>
42   <source network='enp66s0f0_br'/>
43   <target dev='tap01'/>
44   <model type='virtio'/>
45   <driver name='vhost' queues='4'/>
46   <link state='down'/>
47   <address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/>
48 </interface>
49 <interface type='hostdev' managed='yes'>
50   <mac address='52:54:00:00:12:53'/>
51   <source>
52     <address type='pci' domain='0x0000' bus='0x42' slot='0x02' function='0x5'/>
53   </source>
54   <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/>
55 </interface>
56
57Booting a VM with the above configuration will result in the following 3
58netdevs created in the VM.
59
604: ens10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
61    link/ether 52:54:00:00:12:53 brd ff:ff:ff:ff:ff:ff
62    inet 192.168.12.53/24 brd 192.168.12.255 scope global dynamic ens10
63       valid_lft 42482sec preferred_lft 42482sec
64    inet6 fe80::97d8:db2:8c10:b6d6/64 scope link
65       valid_lft forever preferred_lft forever
665: ens10nsby: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel master ens10 state UP group default qlen 1000
67    link/ether 52:54:00:00:12:53 brd ff:ff:ff:ff:ff:ff
687: ens11: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq 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
71ens10 is the 'failover' master netdev, ens10nsby and ens11 are the slave
72'standby' and 'primary' netdevs respectively.
73
74Live Migration of a VM with SR-IOV VF & virtio-net in STANDBY mode
75==================================================================
76
77net_failover also enables hypervisor controlled live migration to be supported
78with VMs that have direct attached SR-IOV VF devices by automatic failover to
79the paravirtual datapath when the VF is unplugged.
80
81Here is a sample script that shows the steps to initiate live migration on
82the source hypervisor.
83
84# cat vf_xml
85<interface type='hostdev' managed='yes'>
86  <mac address='52:54:00:00:12:53'/>
87  <source>
88    <address type='pci' domain='0x0000' bus='0x42' slot='0x02' function='0x5'/>
89  </source>
90  <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/>
91</interface>
92
93# Source Hypervisor
94#!/bin/bash
95
96DOMAIN=fedora27-tap01
97PF=enp66s0f0
98VF_NUM=5
99TAP_IF=tap01
100VF_XML=
101
102MAC=52:54:00:00:12:53
103ZERO_MAC=00:00:00:00:00:00
104
105virsh domif-setlink $DOMAIN $TAP_IF up
106bridge fdb del $MAC dev $PF master
107virsh detach-device $DOMAIN $VF_XML
108ip link set $PF vf $VF_NUM mac $ZERO_MAC
109
110virsh migrate --live $DOMAIN qemu+ssh://$REMOTE_HOST/system
111
112# Destination Hypervisor
113#!/bin/bash
114
115virsh attach-device $DOMAIN $VF_XML
116virsh domif-setlink $DOMAIN $TAP_IF down
117