drvbhyve.html.in

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <body>
    <h1>Bhyve driver</h1>

    <ul id="toc"></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></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></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>
&lt;domain type='bhyve'&gt;
    &lt;name&gt;bhyve&lt;/name&gt;
    &lt;uuid&gt;df3be7e7-a104-11e3-aeb0-50e5492bd3dc&lt;/uuid&gt;
    &lt;memory&gt;219136&lt;/memory&gt;
    &lt;currentMemory&gt;219136&lt;/currentMemory&gt;
    &lt;vcpu&gt;1&lt;/vcpu&gt;
    &lt;os&gt;
       &lt;type&gt;hvm&lt;/type&gt;
    &lt;/os&gt;
    &lt;features&gt;
      &lt;apic/&gt;
      &lt;acpi/&gt;
    &lt;/features&gt;
    &lt;clock offset='utc'/&gt;
    &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
    &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
    &lt;on_crash&gt;destroy&lt;/on_crash&gt;
    &lt;devices&gt;
      &lt;disk type='file'&gt;
        &lt;driver name='file' type='raw'/&gt;
        &lt;source file='/path/to/bhyve_freebsd.img'/&gt;
        &lt;target dev='hda' bus='sata'/&gt;
      &lt;/disk&gt;
      &lt;disk type='file' device='cdrom'&gt;
        &lt;driver name='file' type='raw'/&gt;
        &lt;source file='/path/to/cdrom.iso'/&gt;
        &lt;target dev='hdc' bus='sata'/&gt;
        &lt;readonly/&gt;
      &lt;/disk&gt;
      &lt;interface type='bridge'&gt;
        &lt;model type='virtio'/&gt;
        &lt;source bridge="virbr0"/&gt;
      &lt;/interface&gt;
    &lt;/devices&gt;
&lt;/domain&gt;
</pre>

<p>(The &lt;disk&gt; 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 &lt;bootloader&gt;.
</p>

<pre>
&lt;domain type='bhyve'&gt;
    &lt;name&gt;linux_guest&lt;/name&gt;
    &lt;uuid&gt;df3be7e7-a104-11e3-aeb0-50e5492bd3dc&lt;/uuid&gt;
    &lt;memory&gt;131072&lt;/memory&gt;
    &lt;currentMemory&gt;131072&lt;/currentMemory&gt;
    &lt;vcpu&gt;1&lt;/vcpu&gt;
    &lt;bootloader&gt;/usr/local/sbin/grub-bhyve&lt;/bootloader&gt;
    &lt;os&gt;
       &lt;type&gt;hvm&lt;/type&gt;
    &lt;/os&gt;
    &lt;features&gt;
      &lt;apic/&gt;
      &lt;acpi/&gt;
    &lt;/features&gt;
    &lt;clock offset='utc'/&gt;
    &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
    &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
    &lt;on_crash&gt;destroy&lt;/on_crash&gt;
    &lt;devices&gt;
      &lt;disk type='file' device='disk'&gt;
        &lt;driver name='file' type='raw'/&gt;
        &lt;source file='/path/to/guest_hdd.img'/&gt;
        &lt;target dev='hda' bus='sata'/&gt;
      &lt;/disk&gt;
      &lt;disk type='file' device='cdrom'&gt;
        &lt;driver name='file' type='raw'/&gt;
        &lt;source file='/path/to/cdrom.iso'/&gt;
        &lt;target dev='hdc' bus='sata'/&gt;
        &lt;readonly/&gt;
      &lt;/disk&gt;
      &lt;interface type='bridge'&gt;
        &lt;model type='virtio'/&gt;
        &lt;source bridge="virbr0"/&gt;
      &lt;/interface&gt;
    &lt;/devices&gt;
&lt;/domain&gt;
</pre>

<h3>Example config (Linux UEFI guest, VNC, tablet)</h3>

<p>This is an example to boot into Fedora 25 installation:</p>

<pre>
&lt;domain type='bhyve'&gt;
    &lt;name&gt;fedora_uefi_vnc_tablet&lt;/name&gt;
    &lt;memory unit='G'&gt;4&lt;/memory&gt;
    &lt;vcpu&gt;2&lt;/vcpu&gt;
    &lt;os&gt;
       &lt;type&gt;hvm&lt;/type&gt;
       <b>&lt;loader readonly=&quot;yes&quot; type=&quot;pflash&quot;&gt;/usr/local/share/uefi-firmware/BHYVE_UEFI.fd&lt;/loader&gt;</b>
    &lt;/os&gt;
    &lt;features&gt;
      &lt;apic/&gt;
      &lt;acpi/&gt;
    &lt;/features&gt;
    &lt;clock offset='utc'/&gt;
    &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
    &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
    &lt;on_crash&gt;destroy&lt;/on_crash&gt;
    &lt;devices&gt;
      &lt;disk type='file' device='cdrom'&gt;
        &lt;driver name='file' type='raw'/&gt;
          &lt;source file='/path/to/Fedora-Workstation-Live-x86_64-25-1.3.iso'/&gt;
        &lt;target dev='hdc' bus='sata'/&gt;
        &lt;readonly/&gt;
      &lt;/disk&gt;
      &lt;disk type='file' device='disk'&gt;
        &lt;driver name='file' type='raw'/&gt;
        &lt;source file='/path/to/linux_uefi.img'/&gt;
        &lt;target dev='hda' bus='sata'/&gt;
        &lt;/disk&gt;
      &lt;interface type='bridge'&gt;
        &lt;model type='virtio'/&gt;
        &lt;source bridge=&quot;virbr0&quot;/&gt;
      &lt;/interface&gt;
      &lt;serial type=&quot;nmdm&quot;&gt;
        &lt;source master=&quot;/dev/nmdm0A&quot; slave=&quot;/dev/nmdm0B&quot;/&gt;
      &lt;/serial&gt;
      <b>&lt;graphics type='vnc' port='5904'&gt;
        &lt;listen type='address' address='127.0.0.1'/&gt;
      &lt;/graphics&gt;
      &lt;controller type='usb' model='nec-xhci'/&gt;
      &lt;input type='tablet' bus='usb'/&gt;</b>
    &lt;/devices&gt;
&lt;/domain&gt;
</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></h2>

<h3><a id="console">Connecting to a guest console</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>
...
&lt;devices&gt;
  &lt;serial type="nmdm"&gt;
    &lt;source master="/dev/nmdm0A" slave="/dev/nmdm0B"/&gt;
  &lt;/serial&gt;
&lt;/devices&gt;
...</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> An 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></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></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>
...
&lt;disk type='volume' device='disk'&gt;
  &lt;source pool='zfspool' volume='vol1'/&gt;
  &lt;target dev='vdb' bus='virtio'/&gt;
&lt;/disk&gt;
...</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></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
&lt;boot order='N'&gt; 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>
...
&lt;bootloader&gt;/usr/local/sbin/grub-bhyve&lt;/bootloader&gt;
&lt;bootloader_args&gt;...&lt;/bootloader_args&gt;
...
</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></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>
&lt;domain type='bhyve'&gt;
    ...
    &lt;os&gt;
       &lt;type&gt;hvm&lt;/type&gt;
       &lt;loader readonly="yes" type="pflash"&gt;/usr/local/share/uefi-firmware/BHYVE_UEFI.fd&lt;/loader&gt;
    &lt;/os&gt;
    ...
</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>
&lt;domain type='bhyve'&gt;
    &lt;devices&gt;
      ...
      &lt;graphics type='vnc' port='5904'&gt;
        &lt;listen type='address' address='127.0.0.1'/&gt;
      &lt;/graphics&gt;
      &lt;controller type='usb' model='nec-xhci'/&gt;
      &lt;input type='tablet' bus='usb'/&gt;
    &lt;/devices&gt;
    ...
&lt;/domain&gt;
</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>
&lt;domain type='bhyve'&gt;
    &lt;devices&gt;
    ...
      &lt;graphics type='vnc' port='5904'&gt;
        &lt;listen type='address' address='127.0.0.1'/&gt;
      &lt;/graphics&gt;
      &lt;video&gt;
        &lt;driver vgaconf='on'/&gt;
        &lt;model type='gop' heads='1' primary='yes'/&gt;
      &lt;/video&gt;
      ...
    &lt;/devices&gt;
    ...
&lt;/domain&gt;
</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&amp;sektion=8&amp;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>

<h3><a id="clockconfig">Clock configuration</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>
&lt;domain type="bhyve"&gt;
    ...
    &lt;clock offset='utc'/&gt;
    ...
&lt;/domain&gt;
</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>
&lt;domain type="bhyve"&gt;
    ...
    &lt;clock offset='localtime'/&gt;
    ...
&lt;/domain&gt;
</pre>

<h3><a id="e1000">e1000 NIC</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>
...
    &lt;interface type='bridge'&gt;
      &lt;source bridge='virbr0'/&gt;
      &lt;model type='<b>e1000</b>'/&gt;
    &lt;/interface&gt;
...
</pre>

  </body>
</html>