libvirt: Bhyve driver
Description: libvirt, virtualization, virtualization API

# Bhyve driver

Bhyve is a FreeBSD hypervisor. It first appeared in FreeBSD 10.0. However, it's recommended to use the latest supported release 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, if_bridge, and pf 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 pf 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 Using UEFI bootrom, VNC, and USB tablet section for a more detailed explanation.

### Example config (FreeBSD/arm64 guest)

Since 12.0.0, it is possible to run arm64 guests on arm64 hosts.

    <domain type='bhyve'>
      <name>freebsd-15.0R</name>
      <memory unit='G'>2</memory>
      <vcpu>2</vcpu>
      <os>
        <type>hvm</type>
        <loader readonly="yes" type="pflash">/usr/local/share/u-boot/u-boot-bhyve-arm64/u-boot.bin</loader>
      </os>
      <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='/home/novel/FreeBSD-15.0-RELEASE-arm64-aarch64-ufs.raw'/>
          <target dev='vda' bus='virtio'/>
        </disk>
        <interface type='network'>
          <source network='default'/>
          <model type='virtio'/>
        </interface>
        <serial type="nmdm">
          <source master="/dev/nmdmFreeBSDA" slave="/dev/nmdmFreeBSDB"/>
        </serial>
      </devices>
    </domain>

This example uses the bhyve u-boot loader which can be installed from the u-boot-bhyve-arm64 package or the sysutils/u-boot-bhyve-arm64 port.

## 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 Using grub2-bhyve or Alternative Bootloaders, 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.

Since 11.4.0, it's possible to configure an NVRAM file:

    <os>
      <type>hvm</type>
      <loader readonly="yes" type="pflash">/usr/local/share/uefi-firmware/BHYVE_UEFI.fd</loader>
      <nvram template='/usr/local/share/edk2-bhyve/BHYVE_UEFI_VARS.fd'>/var/lib/libvirt/bhyve/nvram/myvm.fd</nvram>
    </os>

Alternatively, it's also possible to let the driver automatically configure the firmware and NVRAM:

    <os firmware='efi'>
      <type>hvm</type>
      <nvram/>
    </os>

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.

Since 11.10.0, the guest can be configured to wait for an incoming VNC connection before booting:

    <graphics type='vnc' port='5904' wait='yes'>
      <listen type='address' address='127.0.0.1'/>
    </graphics>

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

### Random number generator device

Since 11.3.0 it's possible to use the virtio random number generator devices.

Example:

    ...
      <rng model='virtio'>
        <backend model='random'/>
      </rng>
    ...

### TCP console

Since 11.6.0 it's possible to configure TCP console.

Example:

    ...
      <serial type='tcp'>
        <source mode='bind' host='127.0.0.1' service='12345'/>
        <target type='serial' port='0'/>
      </serial>
    ...

Note: there's no direct way to check if the actual bhyve binary supports the TCP console. Thus, libvirt always assumes it's supported. Please refer to the bhyve(1) manual page to make sure.

### NVMe device

Since 11.9.0, it's possible to use NVMe device.

Example:

    ...
      <disk type='file'>
        <driver name='file' type='raw'/>
        <source file='/tmp/freebsd.img'/>
        <target dev='nvme0n1' bus='nvme'/>
      </disk>
     ...

As bhyve(1) uses one NVMe device per PCI address, it's modeled in a way that there is one device per controller. That is, if using more than one NVMe device, for device name users should increment controller number rather than namespace number, i.e.: nvme0n1, nvme1n1, etc.

### Device passthrough

Since 11.10.0, it is possible to passthrough PCI devices.

Example:

    ...
      <hostdev mode='subsystem' type='pci' managed='no'>
        <source>
          <address domain='0x0000' bus='0x01' slot='0x00' function='0x0'/>
        </source>
      </hostdev>
    ...

Using passthrough devices requires wiring guest memory, see Wiring guest memory.

Note: currently, the nodedev driver is not supported on FreeBSD. Users must configure the device for passthrough manually either by using devctl(8) or by setting pptdevs in loader.conf(5). Please refer to the vmm(4) manual page for more details.

### SLIRP networking

Since 12.0.0, it is possible to use SLIRP networking.

Example:

    ...
      <interface type='user'>
        <model type='e1000'/>
      </interface>
    ...

Then the guest will have external network connectivity without any configuration on the host.

Note

This configuration requires SLIRP open mode support by bhyve. It was introduced in FreeBSD -CURRENT in this commit: https://cgit.FreeBSD.org/src/commit/?id=0e62ebd20172f67283bac9526c2aaeaffeb41b45. Unfortunately, there is no (easy) way to probe its support in libvirt, so please consult the bhyve(8) manual page to make sure it is available.

### virtio-scsi

Since 12.0.0, it is possible to use virtio-scsi devices. It uses CAM Target layer (CTL) as a source.

Example:

    ...
      <disk type='ctl'>
        <source dev='/dev/cam/ctl'/>
        <target dev='sda' bus='scsi'/>
      </disk>
    ...

Please refer to cam(4), ctl(4), and ctld(8) manual pages for more details on CAM and CTL.

### NUMA domains configuration

Since 12.2.0, it is possible to configure NUMA domains for the guest.

Example:

    <domain type='bhyve'>
      ...
      <memory unit='KiB'>4194304</memory>
      <vcpu>8</vcpu>
      ...
      <cpu>
        <numa>
          <cell id='0' cpus='0-3' memory='2097152' unit='KiB'/>
          <cell id='1' cpus='4-7' memory='2097152' unit='KiB'/>
        </numa>
      </cpu>
    </domain>

Every NUMA domain must have memory and cpus specified. Bhyve allows configuring up to 8 NUMA domains.

### Virtio-console device

Since 12.4.0, it is possible to use the virtio console device. Example:

    <devices>
      <channel type='unix'>
        <source mode='bind' path='/var/run/libvirt/bhyve/bhyve.agent'/>
        <target type='virtio' name='org.qemu.guest_agent.0'/>
        <address type='virtio-serial' controller='0' bus='0' port='1'/>
      </channel>
    </devices>

Bhyve supports up to 16 ports per console.

## Resource tuning and limiting

The libvirt bhyve driver supports tuning and limiting resources such as CPU, memory, and I/O.

For managing the memory and I/O limits, the bhyve driver uses the rctl(4) framework.

As of FreeBSD 15.0-RELEASE, rctl is not enabled by default. Please refer to the manual page above and the FreeBSD Handbook on how to enable it.

CPU tuning does not require any additional configuration.

### vCPU pinning

Pinning domain vCPUs to the specific host CPUs is supported since 12.1.0.

Example:

    <domain type='bhyve'>
      ...
      <vcpu>2</vcpu>
      <cputune>
        <vcpupin vcpu="0" cpuset="1-4,^2"/>
        <vcpupin vcpu="1" cpuset="0,4"/>
      </cputune>
      ...
    </domain>

### Block I/O tuning

Block I/O tuning is supported since 12.3.0. Sample configuration:

    <blkiotune>
      <device>
        <path>*</path>
        <read_iops_sec>20000</read_iops_sec>
        <write_iops_sec>20000</write_iops_sec>
        <read_bytes_sec>10000</read_bytes_sec>
        <write_bytes_sec>10000</write_bytes_sec>
      </device>
    </blkiotune>

The * path here means that the limits are applied to the domain as a whole. Currently, it is not possible to apply limits to the individual devices of the domain.

### Memory limitation

Setting a memory hard limit for a domain is supported since 12.4.0. Example:

    <memtune>
      <hard_limit unit='M'>512</hard_limit>
    </memtune>

Please refer to the format domain page for considerations on setting hard_limit.

Currently, other memory tuning options (soft_limit, swap_hard_limit, and min_guarantee) are not supported.

## Guest-specific considerations

### Windows

For Windows guests, it is recommended to have the LPC controller on slot 31. As the libvirt driver allocates slot 1 for the LPC controller by default, the address must be specified explicitly:

    <controller type='isa' index='0'>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x1f' function='0x0'/>
    </controller>