From: Peter Krempa Date: Thu, 10 Mar 2022 16:57:53 +0000 (+0100) Subject: docs: Convert 'drvbhyve' page to rST X-Git-Tag: v8.3.0-rc1~238 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4717e591cb0cdcb072ed8d8515706368b43ff190;p=thirdparty%2Flibvirt.git docs: Convert 'drvbhyve' page to rST Signed-off-by: Peter Krempa Reviewed-by: Erik Skultety --- 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 @@ - - - - -

Bhyve driver

- -

-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 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. -

- -

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@example.com/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 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 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 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. 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 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 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 3.2.0, in addition to grub-bhyve, -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 -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 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) -manual page and the bhyve wiki for more details on using -the vgaconf option.

- -

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 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 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 -for 10-STABLE and -in changeset r279225 -for -CURRENT. It's possible to use this in libvirt 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 -bhyve supports Intel e1000 network adapter emulation. It's supported in libvirt -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 -bhyve supports sound device emulation. It's supported in libvirt -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 -bhyve supports sharing arbitrary directory tree between the guest and the host. -It's supported in libvirt 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 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 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 -for -CURRENT. -Example:

-<domain type="bhyve">
-    ...
-    <cpu>
-      <topology sockets='1' cores='2' threads='1'/>
-    </cpu>
-    ...
-</domain>
-

- -

Ignoring unknown MSRs reads and writes

- -

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 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/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 `__. + +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@example.com/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. + +:: + + + bhyve + df3be7e7-a104-11e3-aeb0-50e5492bd3dc + 219136 + 219136 + 1 + + hvm + + + + + + + destroy + restart + destroy + + + + + + + + + + + + + + + + + + + +(The sections may be swapped in order to install from *cdrom.iso*.) + +Example config (Linux guest) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Note the addition of . + +:: + + + linux_guest + df3be7e7-a104-11e3-aeb0-50e5492bd3dc + 131072 + 131072 + 1 + /usr/local/sbin/grub-bhyve + + hvm + + + + + + + destroy + restart + destroy + + + + + + + + + + + + + + + + + + + +Example config (Linux UEFI guest, VNC, tablet) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is an example to boot into Fedora 25 installation: + +:: + + + fedora_uefi_vnc_tablet + 4 + 2 + + hvm + /usr/local/share/uefi-firmware/BHYVE_UEFI.fd + + + + + + + destroy + restart + destroy + + + + + + + + + + + + + + + + + + + + + + + + + + + +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` ): + +:: + + ... + + + + + + ... + +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 `__. 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: + +:: + + ... + + + + + ... + +Please refer to the `Storage documentation `__ 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 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. + +:: + + ... + /usr/local/sbin/grub-bhyve + ... + ... + +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: + +:: + + + ... + + hvm + /usr/local/share/uefi-firmware/BHYVE_UEFI.fd + + ... + +This uses the UEFI firmware provided by the +`sysutils/bhyve-firmware `__ +FreeBSD port. + +VNC and the tablet input device could be configured this way: + +:: + + + + ... + + + + + + + ... + + +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: + +:: + + + + ... + + + +

+ ... + + ... + + +If not specified, bhyve's default mode for ``vgaconf`` will be used. Please +refer to the +`bhyve(8) `__ +manual page and the `bhyve wiki `__ 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): + +:: + + + +:since:`Since 6.8.0` , it's possible to set framebuffer resolution using the +``resolution`` sub-element: + +:: + +

+ +:since:`Since 6.8.0` , VNC server can be configured to use password based +authentication: + +:: + + + + + +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 `__ for *10-STABLE* +and in `changeset r279225 `__ +for *-CURRENT*. It's possible to use this in libvirt :since:`since 1.2.18` , +just place the following to domain XML: + +:: + + + ... + + ... + + +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: + +:: + + + ... + + ... + + +e1000 NIC +~~~~~~~~~ + +As of `FreeBSD changeset +r302504 `__ bhyve supports +Intel e1000 network adapter emulation. It's supported in libvirt :since:`since +3.1.0` and could be used as follows: + +:: + + ... + + + + + ... + +Sound device +~~~~~~~~~~~~ + +As of `FreeBSD changeset +r349355 `__ bhyve supports +sound device emulation. It's supported in libvirt :since:`since 6.7.0` . + +:: + + ... + +

+ ... + +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 `__ bhyve supports +sharing arbitrary directory tree between the guest and the host. It's supported +in libvirt :since:`since 6.9.0` . + +:: + + ... + + + + + ... + +This share could be made read only by adding the ```` 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: + +:: + + + ... + + + + ... + + +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 `__ +for *-CURRENT*. Example: + +:: + + + ... + + + + ... + + +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: + +:: + + + ... + + ... + + ... + + ... + + +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 ```` +element under ``domain``. To supply an argument, use the element ```` +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: + +:: + + + ... + + + + + +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',