[PATCH 03/29] docs: Convert 'drvbhyve' page to rST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
 docs/drvbhyve.html.in | 583 ------------------------------------------
 docs/drvbhyve.rst     | 582 +++++++++++++++++++++++++++++++++++++++++
 docs/meson.build      |   2 +-
 3 files changed, 583 insertions(+), 584 deletions(-)
 delete mode 100644 docs/drvbhyve.html.in
 create mode 100644 docs/drvbhyve.rst

diff --git a/docs/drvbhyve.html.in b/docs/drvbhyve.html.in
deleted file mode 100644
index 228e8b2bd5..0000000000
--- a/docs/drvbhyve.html.in
+++ /dev/null
@@ -1,583 +0,0 @@
-<?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="https://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@xxxxxxxxxxx/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
-<a href="https://svnweb.freebsd.org/changeset/base/262884";>FreeBSD changeset 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></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>
-
-<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>
-    &lt;graphics type='vnc' autoport='yes'&gt;
-</pre>
-
-<p><span class="since">Since 6.8.0</span>, it's possible to set framebuffer resolution
-using the <code>resolution</code> sub-element:</p>
-
-<pre>
-   &lt;video&gt;
-     &lt;model type='gop' heads='1' primary='yes'&gt;
-       &lt;resolution x='800' y='600'/&gt;
-     &lt;/model&gt;
-   &lt;/video&gt;
-</pre>
-
-<p><span class="since">Since 6.8.0</span>, VNC server can be configured to use
-password based authentication:</p>
-
-<pre>
-  &lt;graphics type='vnc' port='5904' passwd='foobar'&gt;
-    &lt;listen type='address' address='127.0.0.1'/&gt;
-  &lt;/graphics&gt;
-</pre>
-
-<p>Note: VNC password authentication is known to be cryptographically weak.
-Additionally, the password is passed as a command line argument in clear text.
-Make sure you understand the risks associated with this feature before using it.</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="https://svnweb.freebsd.org/changeset/base/284894";>FreeBSD changeset r284894</a>
-for <i>10-STABLE</i> and
-in <a href="https://svnweb.freebsd.org/changeset/base/279225";>changeset 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";>FreeBSD changeset 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>
-
-<h3><a id="sound">Sound device</a></h3>
-
-<p>As of <a href="https://svnweb.freebsd.org/changeset/base/349355";>FreeBSD changeset r349355</a>
-bhyve supports sound device emulation. It's supported in libvirt
-<span class="since">since 6.7.0</span>.</p>
-
-<pre>
-...
-  &lt;sound model='ich7'&gt;
-    &lt;audio id='1'/&gt;
-  &lt;/sound&gt;
-  &lt;audio id='1' type='oss'&gt;
-    &lt;input dev='/dev/dsp0'/&gt;
-    &lt;output dev='/dev/dsp0'/&gt;
-  &lt;/audio&gt;
-...
-</pre>
-
-<p>Here, the <code>sound</code> element specifies the sound device as it's exposed
-to the guest, with <code>ich7</code> being the only supported model now,
-and the <code>audio</code> element specifies how the guest device is mapped
-to the host sound device.</p>
-
-<h3><a id="fs-9p">Virtio-9p filesystem</a></h3>
-
-<p>As of <a href="https://svnweb.freebsd.org/changeset/base/366413";>FreeBSD changeset r366413</a>
-bhyve supports sharing arbitrary directory tree between the guest and the host.
-It's supported in libvirt <span class="since">since 6.9.0</span>.</p>
-
-<pre>
-...
-  &lt;filesystem&gt;
-    &lt;source dir='/shared/dir'/&gt;
-    &lt;target dir='shared_dir'/&gt;
-  &lt;/filesystem&gt;
-...
-</pre>
-
-<p>This share could be made read only by adding the <code>&lt;readonly/&gt;</code> sub-element.</p>
-
-<p>In the Linux guest, this could be mounted using:</p>
-
-<pre>mount -t 9p shared_dir /mnt/shared_dir</pre>
-
-<h3><a id="wired">Wiring guest memory</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>
-&lt;domain type="bhyve"&gt;
-    ...
-    &lt;memoryBacking&gt;
-      &lt;locked/&gt;
-    &lt;/memoryBacking&gt;
-    ...
-&lt;/domain&gt;
-</pre>
-
-<h3><a id="cputopology">CPU topology</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="https://svnweb.freebsd.org/changeset/base/332298";>FreeBSD changeset r332298</a>
-for <i>-CURRENT</i>.
-Example:</p>
-<pre>
-&lt;domain type="bhyve"&gt;
-    ...
-    &lt;cpu&gt;
-      &lt;topology sockets='1' cores='2' threads='1'/&gt;
-    &lt;/cpu&gt;
-    ...
-&lt;/domain&gt;
-</pre>
-
-<h3><a id="msrs">Ignoring unknown MSRs reads and writes</a></h3>
-
-<p><span class="since">Since 5.1.0</span>, it's possible to make bhyve
-ignore accesses to unimplemented Model Specific Registers (MSRs).
-Example:</p>
-
-<pre>
-&lt;domain type="bhyve"&gt;
-    ...
-    &lt;features&gt;
-      ...
-      &lt;msrs unknown='ignore'/&gt;
-      ...
-    &lt;/features&gt;
-    ...
-&lt;/domain&gt;
-</pre>
-
-<h3><a id="bhyvecommand">Pass-through of arbitrary bhyve commands</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>&lt;bhyve:commandline&gt;</code> element under <code>domain</code>.
-To supply an argument, use the element <code>&lt;bhyve:arg&gt;</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>
-&lt;domain type="bhyve" xmlns:bhyve="http://libvirt.org/schemas/domain/bhyve/1.0"&gt;
-  ...
-  &lt;bhyve:commandline&gt;
-    &lt;bhyve:arg value='-somebhyvearg'/&gt;
-  &lt;/bhyve:commandline&gt;
-&lt;/domain&gt;
-</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>
-
-  </body>
-</html>
diff --git a/docs/drvbhyve.rst b/docs/drvbhyve.rst
new file mode 100644
index 0000000000..95ef4e9b49
--- /dev/null
+++ b/docs/drvbhyve.rst
@@ -0,0 +1,582 @@
+.. role:: since
+
+============
+Bhyve driver
+============
+
+.. contents::
+
+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 ``vmm`` kernel module. Additionally, ``if_tap`` and ``if_bridge``
+modules should be loaded for networking support. Also, :since:`since 3.2.0` the
+``virt-host-validate(1)`` supports the bhyve host validation and could be used
+like this:
+
+::
+
+   $ 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
+   $
+
+Additional information on bhyve could be obtained on
+`bhyve.org <https://bhyve.org/>`__.
+
+Connections to the Bhyve driver
+-------------------------------
+
+The libvirt bhyve driver is a single-instance privileged driver. Some sample
+connection URIs are:
+
+::
+
+   bhyve:///system                     (local access)
+   bhyve+unix:///system                (local access)
+   bhyve+ssh://root@xxxxxxxxxxx/system (remote access, SSH tunnelled)
+
+Example guest domain XML configurations
+---------------------------------------
+
+Example config
+~~~~~~~~~~~~~~
+
+The bhyve driver in libvirt is in its early stage and under active development.
+So it supports only limited number of features bhyve provides.
+
+Note: in older libvirt versions, only a single network device and a single disk
+device were supported per-domain. However, :since:`since 1.2.6` the libvirt
+bhyve driver supports up to 31 PCI devices.
+
+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.
+
+Note: Only the SATA bus is supported. Only ``cdrom``- and ``disk``-type disks
+are supported.
+
+::
+
+   <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>
+
+(The <disk> sections may be swapped in order to install from *cdrom.iso*.)
+
+Example config (Linux guest)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note the addition of <bootloader>.
+
+::
+
+   <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>
+
+Example config (Linux UEFI guest, VNC, tablet)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an example to boot into Fedora 25 installation:
+
+::
+
+   <domain type='bhyve'>
+       <name>fedora_uefi_vnc_tablet</name>
+       <memory unit='G'>4</memory>
+       <vcpu>2</vcpu>
+       <os>
+          <type>hvm</type>
+          <loader readonly="yes" type="pflash">/usr/local/share/uefi-firmware/BHYVE_UEFI.fd</loader>
+       </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>
+         <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>
+
+Please refer to the `UEFI <#uefi>`__ section for a more detailed explanation.
+
+Guest usage / management
+------------------------
+
+Connecting to a guest console
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Guest console connection is supported through the ``nmdm`` device. It could be
+enabled by adding the following to the domain XML ( :since:`Since 1.2.4` ):
+
+::
+
+   ...
+   <devices>
+     <serial type="nmdm">
+       <source master="/dev/nmdm0A" slave="/dev/nmdm0B"/>
+     </serial>
+   </devices>
+   ...
+
+Make sure to load the ``nmdm`` kernel module if you plan to use that.
+
+Then ``virsh console`` command can be used to connect to the text console of a
+guest.
+
+**NB:** 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
+changeset r262884 <https://svnweb.freebsd.org/changeset/base/262884>`__. If an
+older version is used, one either has to open a console manually with
+``virsh console`` to let a guest boot or start a guest using:
+
+::
+
+   start --console domname
+
+**NB:** A bootloader configured to require user interaction will prevent the
+domain from starting (and thus ``virsh console`` or ``start --console`` 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. *However,* 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 ``/dev/nmdm0B`` is configured as the slave end of the domain
+serial device) is:
+
+::
+
+   cu -l /dev/nmdm0B
+
+Converting from domain XML to Bhyve args
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh domxml-to-native`` command can preview the actual ``bhyve`` commands
+that will be executed for a given domain. It outputs two lines, the first line
+is a ``bhyveload`` command and the second is a ``bhyve`` command.
+
+Please note that the ``virsh domxml-to-native`` 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 ``tap0`` for the network interface. So if you're going to run
+these commands manually, most likely you might want to tweak them.
+
+::
+
+   # 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
+
+Using ZFS volumes
+~~~~~~~~~~~~~~~~~
+
+It's possible to use ZFS volumes as disk devices :since:`since 1.2.8` . An
+example of domain XML device entry for that will look like:
+
+::
+
+   ...
+   <disk type='volume' device='disk'>
+     <source pool='zfspool' volume='vol1'/>
+     <target dev='vdb' bus='virtio'/>
+   </disk>
+   ...
+
+Please refer to the `Storage documentation <storage.html>`__ for more details on
+storage management.
+
+Using grub2-bhyve or Alternative Bootloaders
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's possible to boot non-FreeBSD guests by specifying an explicit bootloader,
+e.g. ``grub-bhyve(1)``. Arguments to the bootloader may be specified as well. If
+the bootloader is ``grub-bhyve`` 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
+``cdrom``- or ``disk``-type devices). If the disk type is ``disk``, it will
+attempt to boot from the first partition in the disk image.
+
+::
+
+   ...
+   <bootloader>/usr/local/sbin/grub-bhyve</bootloader>
+   <bootloader_args>...</bootloader_args>
+   ...
+
+Caveat: ``bootloader_args`` does not support any quoting. Filenames, etc, must
+not have spaces or they will be tokenized incorrectly.
+
+Using UEFI bootrom, VNC, and USB tablet
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:since:`Since 3.2.0` , in addition to `grub-bhyve <#grubbhyve>`__, non-FreeBSD
+guests could be also booted using an UEFI boot ROM, provided both guest OS and
+installed ``bhyve(1)`` version support UEFI. To use that, ``loader`` should be
+specified in the ``os`` section:
+
+::
+
+   <domain type='bhyve'>
+       ...
+       <os>
+          <type>hvm</type>
+          <loader readonly="yes" type="pflash">/usr/local/share/uefi-firmware/BHYVE_UEFI.fd</loader>
+       </os>
+       ...
+
+This uses the UEFI firmware provided by the
+`sysutils/bhyve-firmware <https://www.freshports.org/sysutils/bhyve-firmware/>`__
+FreeBSD port.
+
+VNC and the tablet input device could be configured this way:
+
+::
+
+   <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>
+
+This way, VNC will be accessible on ``127.0.0.1:5904``.
+
+Please note that the tablet device requires to have a USB controller of the
+``nec-xhci`` model. Currently, only a single controller of this type and a
+single tablet are supported per domain.
+
+:since:`Since 3.5.0` , it's possible to configure how the video device is
+exposed to the guest using the ``vgaconf`` attribute:
+
+::
+
+   <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>
+
+If not specified, bhyve's default mode for ``vgaconf`` will be used. Please
+refer to the
+`bhyve(8) <https://www.freebsd.org/cgi/man.cgi?query=bhyve&sektion=8&manpath=FreeBSD+12-current>`__
+manual page and the `bhyve wiki <https://wiki.freebsd.org/bhyve>`__ for more
+details on using the ``vgaconf`` option.
+
+:since:`Since 3.7.0` , it's possible to use ``autoport`` to let libvirt allocate
+VNC port automatically (instead of explicitly specifying it with the ``port``
+attribute):
+
+::
+
+       <graphics type='vnc' autoport='yes'>
+
+:since:`Since 6.8.0` , it's possible to set framebuffer resolution using the
+``resolution`` sub-element:
+
+::
+
+      <video>
+        <model type='gop' heads='1' primary='yes'>
+          <resolution x='800' y='600'/>
+        </model>
+      </video>
+
+:since:`Since 6.8.0` , VNC server can be configured to use password based
+authentication:
+
+::
+
+     <graphics type='vnc' port='5904' passwd='foobar'>
+       <listen type='address' address='127.0.0.1'/>
+     </graphics>
+
+Note: VNC password authentication is known to be cryptographically weak.
+Additionally, the password is passed as a command line argument in clear text.
+Make sure you understand the risks associated with this feature before using it.
+
+Clock configuration
+~~~~~~~~~~~~~~~~~~~
+
+Originally bhyve supported only localtime for RTC. Support for UTC time was
+introduced in `FreeBSD changeset
+r284894 <https://svnweb.freebsd.org/changeset/base/284894>`__ for *10-STABLE*
+and in `changeset r279225 <https://svnweb.freebsd.org/changeset/base/279225>`__
+for *-CURRENT*. It's possible to use this in libvirt :since:`since 1.2.18` ,
+just place the following to domain XML:
+
+::
+
+   <domain type="bhyve">
+       ...
+       <clock offset='utc'/>
+       ...
+   </domain>
+
+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:
+
+::
+
+   <domain type="bhyve">
+       ...
+       <clock offset='localtime'/>
+       ...
+   </domain>
+
+e1000 NIC
+~~~~~~~~~
+
+As of `FreeBSD changeset
+r302504 <https://svnweb.freebsd.org/changeset/base/302504>`__ bhyve supports
+Intel e1000 network adapter emulation. It's supported in libvirt :since:`since
+3.1.0` and could be used as follows:
+
+::
+
+   ...
+       <interface type='bridge'>
+         <source bridge='virbr0'/>
+         <model type='e1000'/>
+       </interface>
+   ...
+
+Sound device
+~~~~~~~~~~~~
+
+As of `FreeBSD changeset
+r349355 <https://svnweb.freebsd.org/changeset/base/349355>`__ bhyve supports
+sound device emulation. It's supported in libvirt :since:`since 6.7.0` .
+
+::
+
+   ...
+     <sound model='ich7'>
+       <audio id='1'/>
+     </sound>
+     <audio id='1' type='oss'>
+       <input dev='/dev/dsp0'/>
+       <output dev='/dev/dsp0'/>
+     </audio>
+   ...
+
+Here, the ``sound`` element specifies the sound device as it's exposed to the
+guest, with ``ich7`` being the only supported model now, and the ``audio``
+element specifies how the guest device is mapped to the host sound device.
+
+Virtio-9p filesystem
+~~~~~~~~~~~~~~~~~~~~
+
+As of `FreeBSD changeset
+r366413 <https://svnweb.freebsd.org/changeset/base/366413>`__ bhyve supports
+sharing arbitrary directory tree between the guest and the host. It's supported
+in libvirt :since:`since 6.9.0` .
+
+::
+
+   ...
+     <filesystem>
+       <source dir='/shared/dir'/>
+       <target dir='shared_dir'/>
+     </filesystem>
+   ...
+
+This share could be made read only by adding the ``<readonly/>`` sub-element.
+
+In the Linux guest, this could be mounted using:
+
+::
+
+   mount -t 9p shared_dir /mnt/shared_dir
+
+Wiring guest memory
+~~~~~~~~~~~~~~~~~~~
+
+:since:`Since 4.4.0` , it's possible to specify that guest memory should be
+wired and cannot be swapped out as follows:
+
+::
+
+   <domain type="bhyve">
+       ...
+       <memoryBacking>
+         <locked/>
+       </memoryBacking>
+       ...
+   </domain>
+
+CPU topology
+~~~~~~~~~~~~
+
+:since:`Since 4.5.0` , it's possible to specify guest CPU topology, if bhyve
+supports that. Support for specifying guest CPU topology was added to bhyve in
+`FreeBSD changeset r332298 <https://svnweb.freebsd.org/changeset/base/332298>`__
+for *-CURRENT*. Example:
+
+::
+
+   <domain type="bhyve">
+       ...
+       <cpu>
+         <topology sockets='1' cores='2' threads='1'/>
+       </cpu>
+       ...
+   </domain>
+
+Ignoring unknown MSRs reads and writes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:since:`Since 5.1.0` , it's possible to make bhyve ignore accesses to
+unimplemented Model Specific Registers (MSRs). Example:
+
+::
+
+   <domain type="bhyve">
+       ...
+       <features>
+         ...
+         <msrs unknown='ignore'/>
+         ...
+       </features>
+       ...
+   </domain>
+
+Pass-through of arbitrary bhyve commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:since:`Since 5.1.0` , it's possible to pass additional command-line arguments
+to the bhyve process when starting the domain using the ``<bhyve:commandline>``
+element under ``domain``. To supply an argument, use the element ``<bhyve:arg>``
+with the attribute ``value`` 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 ``xmlns:name``
+attribute) that pulls in ``http://libvirt.org/schemas/domain/bhyve/1.0``;
+typically, the namespace is given the name of ``bhyve``.
+
+Example:
+
+::
+
+   <domain type="bhyve" xmlns:bhyve="http://libvirt.org/schemas/domain/bhyve/1.0";>
+     ...
+     <bhyve:commandline>
+       <bhyve:arg value='-somebhyvearg'/>
+     </bhyve:commandline>
+   </domain>
+
+Note that these extensions are for testing and development purposes only. They
+are **unsupported**, 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.
diff --git a/docs/meson.build b/docs/meson.build
index bb7e27e031..a6c3077f25 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
   'csharp',
   'dbus',
   'docs',
-  'drvbhyve',
   'drvesx',
   'drvhyperv',
   'drvlxc',
@@ -79,6 +78,7 @@ docs_rst_files = [
   'daemons',
   'downloads',
   'drivers',
+  'drvbhyve',
   'drvch',
   'drvqemu',
   'errors',
-- 
2.35.1




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux