One Hat Cyber Team

Edit File: virtio-net-failover.html

<!DOCTYPE html>

 <html class="no-js" lang="en" > 
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>QEMU virtio-net standby (net_failover) &mdash; QEMU qemu-kvm-6.2.0-53.module+el8.10.0+2055+8eb7870b.4 documentation</title>

</head>

<a href="../index.html" class="icon icon-home"> QEMU

</div>

<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <p class="caption"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../about/index.html">About QEMU</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">System Emulation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quick Start</a></li>
<li class="toctree-l2"><a class="reference internal" href="invocation.html">Invocation</a></li>
<li class="toctree-l2"><a class="reference internal" href="device-emulation.html">Device Emulation</a></li>
<li class="toctree-l2"><a class="reference internal" href="keys.html">Keys in the graphical frontends</a></li>
<li class="toctree-l2"><a class="reference internal" href="mux-chardev.html">Keys in the character backend multiplexer</a></li>
<li class="toctree-l2"><a class="reference internal" href="monitor.html">QEMU Monitor</a></li>
<li class="toctree-l2"><a class="reference internal" href="images.html">Disk Images</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">QEMU virtio-net standby (net_failover)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#restrictions">Restrictions</a></li>
<li class="toctree-l3"><a class="reference internal" href="#usecase">Usecase</a></li>
<li class="toctree-l3"><a class="reference internal" href="#usage">Usage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#hotplug">Hotplug</a></li>
<li class="toctree-l3"><a class="reference internal" href="#migration">Migration</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="linuxboot.html">Direct Linux Boot</a></li>
<li class="toctree-l2"><a class="reference internal" href="generic-loader.html">Generic Loader</a></li>
<li class="toctree-l2"><a class="reference internal" href="guest-loader.html">Guest Loader</a></li>
<li class="toctree-l2"><a class="reference internal" href="barrier.html">QEMU Barrier Client</a></li>
<li class="toctree-l2"><a class="reference internal" href="vnc-security.html">VNC security</a></li>
<li class="toctree-l2"><a class="reference internal" href="tls.html">TLS setup for network services</a></li>
<li class="toctree-l2"><a class="reference internal" href="secrets.html">Providing secret data to QEMU</a></li>
<li class="toctree-l2"><a class="reference internal" href="authz.html">Client authorization</a></li>
<li class="toctree-l2"><a class="reference internal" href="gdb.html">GDB usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="managed-startup.html">Managed start up options</a></li>
<li class="toctree-l2"><a class="reference internal" href="bootindex.html">Managing device boot order with bootindex properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="cpu-hotplug.html">Virtual CPU hotplug</a></li>
<li class="toctree-l2"><a class="reference internal" href="pr-manager.html">Persistent reservation managers</a></li>
<li class="toctree-l2"><a class="reference internal" href="targets.html">QEMU System Emulator Targets</a></li>
<li class="toctree-l2"><a class="reference internal" href="security.html">Security</a></li>
<li class="toctree-l2"><a class="reference internal" href="multi-process.html">Multi-process QEMU</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">User Mode Emulation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../interop/index.html">System Emulation Management and Interoperability</a></li>
<li class="toctree-l1"><a class="reference internal" href="../specs/index.html">System Emulation Guest Hardware Specifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devel/index.html">Developer Information</a></li>
</ul>

</div>
      </div>
    </nav>

<ul class="wy-breadcrumbs">
    
      <li><a href="../index.html">Docs</a> &raquo;</li>
        
          <li><a href="index.html">System Emulation</a> &raquo;</li>
        
      <li>QEMU virtio-net standby (net_failover)</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            
              <a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/system/virtio-net-failover.rst" class="fa fa-gitlab"> Edit on GitLab</a>
            
          
        
      </li>
    
  </ul>

<hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="qemu-virtio-net-standby-net-failover">
<h1>QEMU virtio-net standby (net_failover)<a class="headerlink" href="#qemu-virtio-net-standby-net-failover" title="Permalink to this headline">¶</a></h1>
<p>This document explains the setup and usage of virtio-net standby feature which
is used to create a net_failover pair of devices.</p>
<p>The general idea is that we have a pair of devices, a (vfio-)pci and a
virtio-net device. Before migration the vfio device is unplugged and data flows
through the virtio-net device, on the target side another vfio-pci device is
plugged in to take over the data-path. In the guest the net_failover kernel
module will pair net devices with the same MAC address.</p>
<p>The two devices are called primary and standby device. The fast hardware based
networking device is called the primary device and the virtio-net device is the
standby device.</p>
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>Currently only PCIe devices are allowed as primary devices, this restriction
can be lifted in the future with enhanced QEMU support. Also, only networking
devices are allowed as primary device. The user needs to ensure that primary
and standby devices are not plugged into the same PCIe slot.</p>
</div>
<div class="section" id="usecase">
<h2>Usecase<a class="headerlink" href="#usecase" title="Permalink to this headline">¶</a></h2>
<blockquote>
<div>Virtio-net standby allows easy migration while using a passed-through fast
networking device by falling back to a virtio-net device for the duration of
the migration. It is like a simple version of a bond, the difference is that it
requires no configuration in the guest. When a guest is live-migrated to
another host QEMU will unplug the primary device via the PCIe based hotplug
handler and traffic will go through the virtio-net device.  On the target
system the primary device will be automatically plugged back and the
net_failover module registers it again as the primary device.</div></blockquote>
</div>
<div class="section" id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<blockquote>
<div><p>The primary device can be hotplugged or be part of the startup configuration</p>
<dl class="docutils">
<dt>-device virtio-net-pci,netdev=hostnet1,id=net1,mac=52:54:00:6f:55:cc, </dt>
<dd>bus=root2,failover=on</dd>
</dl>
<p>With the parameter failover=on the VIRTIO_NET_F_STANDBY feature will be enabled.</p>
<p>-device vfio-pci,host=5e:00.2,id=hostdev0,bus=root1,failover_pair_id=net1</p>
<p>failover_pair_id references the id of the virtio-net standby device. This
is only for pairing the devices within QEMU. The guest kernel module
net_failover will match devices with identical MAC addresses.</p>
</div></blockquote>
</div>
<div class="section" id="hotplug">
<h2>Hotplug<a class="headerlink" href="#hotplug" title="Permalink to this headline">¶</a></h2>
<blockquote>
<div>Both primary and standby device can be hotplugged via the QEMU monitor.  Note
that if the virtio-net device is plugged first a warning will be issued that it
couldn’t find the primary device.</div></blockquote>
</div>
<div class="section" id="migration">
<h2>Migration<a class="headerlink" href="#migration" title="Permalink to this headline">¶</a></h2>
<blockquote>
<div>A new migration state wait-unplug was added for this feature. If failover primary
devices are present in the configuration, migration will go into this state.
It will wait until the device unplug is completed in the guest and then move into
active state. On the target system the primary devices will be automatically hotplugged
when the feature bit was negotiated for the virtio-net standby device.</div></blockquote>
</div>
</div>

</div>
           
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="linuxboot.html" class="btn btn-neutral float-right" title="Direct Linux Boot" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="images.html" class="btn btn-neutral" title="Disk Images" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>

<hr/>

<div role="contentinfo">
    <p>
        &copy; Copyright 2021, The QEMU Project Developers.

</p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

<p></p>

<p>This documentation is for QEMU version 6.2.0.</p>

<p><a href="../about/license.html">QEMU and this manual are released under the
GNU General Public License, version 2.</a></p>

</footer>

</div>
      </div>

</section>

</div>

</body>
</html>