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