<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<!--
This file is autogenerated from drvbhyve.html.in
Do not edit this file. Changes will be lost.
-->
<!--
This page was generated at Tue Jul 2 19:50:20 UTC 2019.
-->
<head>
<meta charset="UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<link rel="stylesheet" type="text/css" href="main.css"/>
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"/>
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"/>
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"/>
<link rel="manifest" href="/manifest.json"/>
<meta name="theme-color" content="#ffffff"/>
<title>libvirt: Bhyve driver</title>
<meta name="description" content="libvirt, virtualization, virtualization API"/>
<script type="text/javascript" src="js/main.js">
<!--// forces non-empty element-->
</script>
</head>
<body onload="pageload()">
<div id="body">
<div id="content">
<h1>Bhyve driver</h1>
<ul>
<li>
<a href="#uri">Connections to the Bhyve driver</a>
</li>
<li>
<a href="#exconfig">Example guest domain XML configurations</a>
</li>
<li>
<a href="#usage">Guest usage / management</a>
<ul>
<li>
<a href="#console">Connecting to a guest console</a>
</li>
<li>
<a href="#xmltonative">Converting from domain XML to Bhyve args</a>
</li>
<li>
<a href="#zfsvolume">Using ZFS volumes</a>
</li>
<li>
<a href="#grubbhyve">Using grub2-bhyve or Alternative Bootloaders</a>
</li>
<li>
<a href="#uefi">Using UEFI bootrom, VNC, and USB tablet</a>
</li>
<li>
<a href="#clockconfig">Clock configuration</a>
</li>
<li>
<a href="#e1000">e1000 NIC</a>
</li>
<li>
<a href="#wired">Wiring guest memory</a>
</li>
<li>
<a href="#cputopology">CPU topology</a>
</li>
<li>
<a href="#bhyvecommand">Pass-through of arbitrary bhyve commands</a>
</li>
</ul>
</li>
</ul>
<p>
Bhyve is a FreeBSD hypervisor. It first appeared in FreeBSD 10.0. However, it's
recommended to keep tracking FreeBSD 10-STABLE to make sure all new features
of bhyve are supported.
In order to enable bhyve on your FreeBSD host, you'll need to load the <code>vmm</code>
kernel module. Additionally, <code>if_tap</code> and <code>if_bridge</code> modules
should be loaded for networking support. Also, <span class="since">since 3.2.0</span> the
<code>virt-host-validate(1)</code> supports the bhyve host validation and could be
used like this:
</p>
<pre>
$ virt-host-validate bhyve
BHYVE: Checking for vmm module : PASS
BHYVE: Checking for if_tap module : PASS
BHYVE: Checking for if_bridge module : PASS
BHYVE: Checking for nmdm module : PASS
$
</pre>
<p>
Additional information on bhyve could be obtained on <a href="http://bhyve.org/">bhyve.org</a>.
</p>
<h2>
<a id="uri">Connections to the Bhyve driver</a>
<a class="headerlink" href="#uri" title="Permalink to this headline">¶</a>
</h2>
<p>
The libvirt bhyve driver is a single-instance privileged driver. Some sample
connection URIs are:
</p>
<pre>
bhyve:///system (local access)
bhyve+unix:///system (local access)
bhyve+ssh://root@example.com/system (remote access, SSH tunnelled)
</pre>
<h2>
<a id="exconfig">Example guest domain XML configurations</a>
<a class="headerlink" href="#exconfig" title="Permalink to this headline">¶</a>
</h2>
<h3>Example config</h3>
<p>
The bhyve driver in libvirt is in its early stage and under active development. So it supports
only limited number of features bhyve provides.
</p>
<p>
Note: in older libvirt versions, only a single network device and a single
disk device were supported per-domain. However,
<span class="since">since 1.2.6</span> the libvirt bhyve driver supports
up to 31 PCI devices.
</p>
<p>
Note: the Bhyve driver in libvirt will boot whichever device is first. If you
want to install from CD, put the CD device first. If not, put the root HDD
first.
</p>
<p>
Note: Only the SATA bus is supported. Only <code>cdrom</code>- and
<code>disk</code>-type disks are supported.
</p>
<pre>
<domain type='bhyve'>
<name>bhyve</name>
<uuid>df3be7e7-a104-11e3-aeb0-50e5492bd3dc</uuid>
<memory>219136</memory>
<currentMemory>219136</currentMemory>
<vcpu>1</vcpu>
<os>
<type>hvm</type>
</os>
<features>
<apic/>
<acpi/>
</features>
<clock offset='utc'/>
<on_poweroff>destroy</on_poweroff>
<on_reboot>restart</on_reboot>
<on_crash>destroy</on_crash>
<devices>
<disk type='file'>
<driver name='file' type='raw'/>
<source file='/path/to/bhyve_freebsd.img'/>
<target dev='hda' bus='sata'/>
</disk>
<disk type='file' device='cdrom'>
<driver name='file' type='raw'/>
<source file='/path/to/cdrom.iso'/>
<target dev='hdc' bus='sata'/>
<readonly/>
</disk>
<interface type='bridge'>
<model type='virtio'/>
<source bridge="virbr0"/>
</interface>
</devices>
</domain>
</pre>
<p>(The <disk> sections may be swapped in order to install from
<em>cdrom.iso</em>.)</p>
<h3>Example config (Linux guest)</h3>
<p>
Note the addition of <bootloader>.
</p>
<pre>
<domain type='bhyve'>
<name>linux_guest</name>
<uuid>df3be7e7-a104-11e3-aeb0-50e5492bd3dc</uuid>
<memory>131072</memory>
<currentMemory>131072</currentMemory>
<vcpu>1</vcpu>
<bootloader>/usr/local/sbin/grub-bhyve</bootloader>
<os>
<type>hvm</type>
</os>
<features>
<apic/>
<acpi/>
</features>
<clock offset='utc'/>
<on_poweroff>destroy</on_poweroff>
<on_reboot>restart</on_reboot>
<on_crash>destroy</on_crash>
<devices>
<disk type='file' device='disk'>
<driver name='file' type='raw'/>
<source file='/path/to/guest_hdd.img'/>
<target dev='hda' bus='sata'/>
</disk>
<disk type='file' device='cdrom'>
<driver name='file' type='raw'/>
<source file='/path/to/cdrom.iso'/>
<target dev='hdc' bus='sata'/>
<readonly/>
</disk>
<interface type='bridge'>
<model type='virtio'/>
<source bridge="virbr0"/>
</interface>
</devices>
</domain>
</pre>
<h3>Example config (Linux UEFI guest, VNC, tablet)</h3>
<p>This is an example to boot into Fedora 25 installation:</p>
<pre>
<domain type='bhyve'>
<name>fedora_uefi_vnc_tablet</name>
<memory unit='G'>4</memory>
<vcpu>2</vcpu>
<os>
<type>hvm</type>
<b><loader readonly="yes" type="pflash">/usr/local/share/uefi-firmware/BHYVE_UEFI.fd</loader></b>
</os>
<features>
<apic/>
<acpi/>
</features>
<clock offset='utc'/>
<on_poweroff>destroy</on_poweroff>
<on_reboot>restart</on_reboot>
<on_crash>destroy</on_crash>
<devices>
<disk type='file' device='cdrom'>
<driver name='file' type='raw'/>
<source file='/path/to/Fedora-Workstation-Live-x86_64-25-1.3.iso'/>
<target dev='hdc' bus='sata'/>
<readonly/>
</disk>
<disk type='file' device='disk'>
<driver name='file' type='raw'/>
<source file='/path/to/linux_uefi.img'/>
<target dev='hda' bus='sata'/>
</disk>
<interface type='bridge'>
<model type='virtio'/>
<source bridge="virbr0"/>
</interface>
<serial type="nmdm">
<source master="/dev/nmdm0A" slave="/dev/nmdm0B"/>
</serial>
<b><graphics type='vnc' port='5904'>
<listen type='address' address='127.0.0.1'/>
</graphics>
<controller type='usb' model='nec-xhci'/>
<input type='tablet' bus='usb'/></b>
</devices>
</domain>
</pre>
<p>Please refer to the <a href="#uefi">UEFI</a> section for a more detailed explanation.</p>
<h2>
<a id="usage">Guest usage / management</a>
<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a>
</h2>
<h3>
<a id="console">Connecting to a guest console</a>
<a class="headerlink" href="#console" title="Permalink to this headline">¶</a>
</h3>
<p>
Guest console connection is supported through the <code>nmdm</code> device. It could be enabled by adding
the following to the domain XML (<span class="since">Since 1.2.4</span>):
</p>
<pre>
...
<devices>
<serial type="nmdm">
<source master="/dev/nmdm0A" slave="/dev/nmdm0B"/>
</serial>
</devices>
...</pre>
<p>Make sure to load the <code>nmdm</code> kernel module if you plan to use that.</p>
<p>
Then <code>virsh console</code> command can be used to connect to the text console
of a guest.</p>
<p><b>NB:</b> Some versions of bhyve have a bug that prevents guests from booting
until the console is opened by a client. This bug was fixed in FreeBSD
<a href="http://svnweb.freebsd.org/changeset/base/262884">r262884</a>. If
an older version is used, one either has to open a console manually with <code>virsh console</code>
to let a guest boot or start a guest using:</p>
<pre>start --console domname</pre>
<p><b>NB:</b> A bootloader configured to require user interaction will prevent
the domain from starting (and thus <code>virsh console</code> or <code>start
--console</code> from functioning) until the user interacts with it manually on
the VM host. Because users typically do not have access to the VM host,
interactive bootloaders are unsupported by libvirt. <em>However,</em> if you happen to
run into this scenario and also happen to have access to the Bhyve host
machine, you may select a boot option and allow the domain to finish starting
by using an alternative terminal client on the VM host to connect to the
domain-configured null modem device. One example (assuming
<code>/dev/nmdm0B</code> is configured as the slave end of the domain serial
device) is:</p>
<pre>cu -l /dev/nmdm0B</pre>
<h3>
<a id="xmltonative">Converting from domain XML to Bhyve args</a>
<a class="headerlink" href="#xmltonative" title="Permalink to this headline">¶</a>
</h3>
<p>
The <code>virsh domxml-to-native</code> command can preview the actual
<code>bhyve</code> commands that will be executed for a given domain.
It outputs two lines, the first line is a <code>bhyveload</code> command and
the second is a <code>bhyve</code> command.
</p>
<p>Please note that the <code>virsh domxml-to-native</code> doesn't do any
real actions other than printing the command, for example, it doesn't try to
find a proper TAP interface and create it, like what is done when starting
a domain; and always returns <code>tap0</code> for the network interface. So
if you're going to run these commands manually, most likely you might want to
tweak them.</p>
<pre>
# virsh -c "bhyve:///system" domxml-to-native --format bhyve-argv --xml /path/to/bhyve.xml
/usr/sbin/bhyveload -m 214 -d /home/user/vm1.img vm1
/usr/sbin/bhyve -c 2 -m 214 -A -I -H -P -s 0:0,hostbridge -s 3:0,virtio-net,tap0,mac=52:54:00:5d:74:e3 -s 2:0,virtio-blk,/home/user/vm1.img -s 1,lpc -l com1,/dev/nmdm0A vm1
</pre>
<h3>
<a id="zfsvolume">Using ZFS volumes</a>
<a class="headerlink" href="#zfsvolume" title="Permalink to this headline">¶</a>
</h3>
<p>It's possible to use ZFS volumes as disk devices <span class="since">since 1.2.8</span>.
An example of domain XML device entry for that will look like:</p>
<pre>
...
<disk type='volume' device='disk'>
<source pool='zfspool' volume='vol1'/>
<target dev='vdb' bus='virtio'/>
</disk>
...</pre>
<p>Please refer to the <a href="storage.html">Storage documentation</a> for more details on storage
management.</p>
<h3>
<a id="grubbhyve">Using grub2-bhyve or Alternative Bootloaders</a>
<a class="headerlink" href="#grubbhyve" title="Permalink to this headline">¶</a>
</h3>
<p>It's possible to boot non-FreeBSD guests by specifying an explicit
bootloader, e.g. <code>grub-bhyve(1)</code>. Arguments to the bootloader may be
specified as well. If the bootloader is <code>grub-bhyve</code> and arguments
are omitted, libvirt will try and infer boot ordering from user-supplied
<boot order='N'> configuration in the domain. Failing that, it will boot
the first disk in the domain (either <code>cdrom</code>- or
<code>disk</code>-type devices). If the disk type is <code>disk</code>, it will
attempt to boot from the first partition in the disk image.</p>
<pre>
...
<bootloader>/usr/local/sbin/grub-bhyve</bootloader>
<bootloader_args>...</bootloader_args>
...
</pre>
<p>Caveat: <code>bootloader_args</code> does not support any quoting.
Filenames, etc, must not have spaces or they will be tokenized incorrectly.</p>
<h3>
<a id="uefi">Using UEFI bootrom, VNC, and USB tablet</a>
<a class="headerlink" href="#uefi" title="Permalink to this headline">¶</a>
</h3>
<p><span class="since">Since 3.2.0</span>, in addition to <a href="#grubbhyve">grub-bhyve</a>,
non-FreeBSD guests could be also booted using an UEFI boot ROM, provided both guest OS and
installed <code>bhyve(1)</code> version support UEFI. To use that, <code>loader</code>
should be specified in the <code>os</code> section:</p>
<pre>
<domain type='bhyve'>
...
<os>
<type>hvm</type>
<loader readonly="yes" type="pflash">/usr/local/share/uefi-firmware/BHYVE_UEFI.fd</loader>
</os>
...
</pre>
<p>This uses the UEFI firmware provided by
the <a href="https://www.freshports.org/sysutils/bhyve-firmware/">sysutils/bhyve-firmware</a>
FreeBSD port.</p>
<p>VNC and the tablet input device could be configured this way:</p>
<pre>
<domain type='bhyve'>
<devices>
...
<graphics type='vnc' port='5904'>
<listen type='address' address='127.0.0.1'/>
</graphics>
<controller type='usb' model='nec-xhci'/>
<input type='tablet' bus='usb'/>
</devices>
...
</domain>
</pre>
<p>This way, VNC will be accessible on <code>127.0.0.1:5904</code>.</p>
<p>Please note that the tablet device requires to have a USB controller
of the <code>nec-xhci</code> model. Currently, only a single controller of this
type and a single tablet are supported per domain.</p>
<p><span class="since">Since 3.5.0</span>, it's possible to configure how the video device is exposed
to the guest using the <code>vgaconf</code> attribute:</p>
<pre>
<domain type='bhyve'>
<devices>
...
<graphics type='vnc' port='5904'>
<listen type='address' address='127.0.0.1'/>
</graphics>
<video>
<driver vgaconf='on'/>
<model type='gop' heads='1' primary='yes'/>
</video>
...
</devices>
...
</domain>
</pre>
<p>If not specified, bhyve's default mode for <code>vgaconf</code>
will be used. Please refer to the
<a href="https://www.freebsd.org/cgi/man.cgi?query=bhyve&sektion=8&manpath=FreeBSD+12-current">bhyve(8)</a>
manual page and the <a href="https://wiki.freebsd.org/bhyve">bhyve wiki</a> for more details on using
the <code>vgaconf</code> option.</p>
<p><span class="since">Since 3.7.0</span>, it's possible to use <code>autoport</code>
to let libvirt allocate VNC port automatically (instead of explicitly specifying
it with the <code>port</code> attribute):</p>
<pre>
<graphics type='vnc' autoport='yes'>
</pre>
<h3>
<a id="clockconfig">Clock configuration</a>
<a class="headerlink" href="#clockconfig" title="Permalink to this headline">¶</a>
</h3>
<p>Originally bhyve supported only localtime for RTC. Support for UTC time was introduced in
<a href="http://svnweb.freebsd.org/changeset/base/284894">r284894</a> for <i>10-STABLE</i> and
in <a href="http://svnweb.freebsd.org/changeset/base/279225">r279225</a> for <i>-CURRENT</i>.
It's possible to use this in libvirt <span class="since">since 1.2.18</span>, just place the
following to domain XML:</p>
<pre>
<domain type="bhyve">
...
<clock offset='utc'/>
...
</domain>
</pre>
<p>Please note that if you run the older bhyve version that doesn't support UTC time, you'll
fail to start a domain. As UTC is used as a default when you do not specify clock settings,
you'll need to explicitly specify 'localtime' in this case:</p>
<pre>
<domain type="bhyve">
...
<clock offset='localtime'/>
...
</domain>
</pre>
<h3>
<a id="e1000">e1000 NIC</a>
<a class="headerlink" href="#e1000" title="Permalink to this headline">¶</a>
</h3>
<p>As of <a href="https://svnweb.freebsd.org/changeset/base/302504">r302504</a> bhyve
supports Intel e1000 network adapter emulation. It's supported in libvirt
<span class="since">since 3.1.0</span> and could be used as follows:</p>
<pre>
...
<interface type='bridge'>
<source bridge='virbr0'/>
<model type='<b>e1000</b>'/>
</interface>
...
</pre>
<h3>
<a id="wired">Wiring guest memory</a>
<a class="headerlink" href="#wired" title="Permalink to this headline">¶</a>
</h3>
<p><span class="since">Since 4.4.0</span>, it's possible to specify that guest memory should
be wired and cannot be swapped out as follows:</p>
<pre>
<domain type="bhyve">
...
<memoryBacking>
<locked/>
</memoryBacking>
...
</domain>
</pre>
<h3>
<a id="cputopology">CPU topology</a>
<a class="headerlink" href="#cputopology" title="Permalink to this headline">¶</a>
</h3>
<p><span class="since">Since 4.5.0</span>, it's possible to specify guest CPU topology, if bhyve
supports that. Support for specifying guest CPU topology was added to bhyve in
<a href="http://svnweb.freebsd.org/changeset/base/332298">r332298</a> for <i>-CURRENT</i>.
Example:</p>
<pre>
<domain type="bhyve">
...
<cpu>
<topology sockets='1' cores='2' threads='1'/>
</cpu>
...
</domain>
</pre>
<h3>
<a id="bhyvecommand">Pass-through of arbitrary bhyve commands</a>
<a class="headerlink" href="#bhyvecommand" title="Permalink to this headline">¶</a>
</h3>
<p><span class="since">Since 5.1.0</span>, it's possible to pass additional command-line
arguments to the bhyve process when starting the domain using the
<code><bhyve:commandline></code> element under <code>domain</code>.
To supply an argument, use the element <code><bhyve:arg></code> with
the attribute <code>value</code> set to additional argument to be added.
The arg element may be repeated multiple times. To use this XML addition, it is necessary
to issue an XML namespace request (the special <code>xmlns:<i>name</i></code> attribute)
that pulls in <code>http://libvirt.org/schemas/domain/bhyve/1.0</code>;
typically, the namespace is given the name of <code>bhyve</code>.
</p>
<p>Example:</p>
<pre>
<domain type="bhyve" xmlns:bhyve="http://libvirt.org/schemas/domain/bhyve/1.0">
...
<bhyve:commandline>
<bhyve:arg value='-somebhyvearg'/>
</bhyve:commandline>
</domain>
</pre>
<p>Note that these extensions are for testing and development purposes only.
They are <b>unsupported</b>, using them may result in inconsistent state,
and upgrading either bhyve or libvirtd maybe break behavior of a domain that
was relying on a specific commands pass-through.</p>
</div>
</div>
<div id="nav">
<div id="home">
<a href="index.html">Home</a>
</div>
<div id="jumplinks">
<ul>
<li>
<a href="downloads.html">Download</a>
</li>
<li>
<a href="contribute.html">Contribute</a>
</li>
<li>
<a href="docs.html">Docs</a>
</li>
</ul>
</div>
<div id="search">
<form id="simplesearch" action="https://www.google.com/search" enctype="application/x-www-form-urlencoded" method="get">
<div>
<input id="searchsite" name="sitesearch" type="hidden" value="libvirt.org"/>
<input id="searchq" name="q" type="text" size="12" value=""/>
<input name="submit" type="submit" value="Go"/>
</div>
</form>
<div id="advancedsearch">
<span>
<input type="radio" name="what" id="whatwebsite" checked="checked" value="website"/>
<label for="whatwebsite">Website</label>
</span>
<span>
<input type="radio" name="what" id="whatwiki" value="wiki"/>
<label for="whatwiki">Wiki</label>
</span>
<span>
<input type="radio" name="what" id="whatdevs" value="devs"/>
<label for="whatdevs">Developers list</label>
</span>
<span>
<input type="radio" name="what" id="whatusers" value="users"/>
<label for="whatusers">Users list</label>
</span>
</div>
</div>
</div>
<div id="footer">
<div id="contact">
<h3>Contact</h3>
<ul>
<li>
<a href="contact.html#email">email</a>
</li>
<li>
<a href="contact.html#irc">irc</a>
</li>
</ul>
</div>
<div id="community">
<h3>Community</h3>
<ul>
<li>
<a href="https://twitter.com/hashtag/libvirt">twitter</a>
</li>
<li>
<a href="http://stackoverflow.com/questions/tagged/libvirt">stackoverflow</a>
</li>
<li>
<a href="http://serverfault.com/questions/tagged/libvirt">serverfault</a>
</li>
</ul>
</div>
<div id="conduct">
Participants in the libvirt project agree to abide by <a href="governance.html#codeofconduct">the project code of conduct</a></div>
<br class="clear"/>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
0a67499d76b7ed32632abafb78e24a2f
>
files
>
83
