Tribblix: manual page: bhyve

BHYVE_CONFIG(5) File Formats and Configurations BHYVE_CONFIG(5)

NAME

bhyve_config - bhyve configuration variables

DESCRIPTION

bhyve(8) uses a hierarchical tree of configuration variables to
describe global and per-device settings. Internal nodes in this tree
do not have a value, only leaf nodes have values. This manual
describes the configuration variables understood by bhyve(8). If
additional variables are defined, bhyve(8) will ignore them and will
not emit errors for unknown variables. However, these additional
variables can be referenced by other variables as described below.

VARIABLE VALUES

Configuration variable values are stored as strings. A configuration
variable value may refer to one or more other configuration values by
name. Instances of the pattern `%(var)' are replaced by the value of
the configuration variable var. To avoid unwanted expansion, `%'
characters can be escaped by a leading `%'. For example, if a
configuration variable disk uses the value /dev/zvol/bhyve/%(name),
then the final value of the disk variable will be set to the path of a
ZFS volume whose name matches the name of the virtual machine on the
pool bhyve.

Some configuration variables may be interpreted as a boolean value.
For those variables the following case-insensitive values may be used
to indicate true:

+o true
+o on
+o yes
+o 1

The following values may be used to indicate false:

+o false
+o off
+o no
+o 0

Some configuration variables may be interpreted as an integer. For
those variables, any syntax supported by strtoul(3C) may be used.

GLOBAL SETTINGS

Architecture Neutral Settings

Name Format Default Description
name string The name of the VM.
cpus integer 1 The total number of
virtual CPUs.
cores integer 1 The number of virtual
cores in each virtual
socket.
threads integer 1 The number of virtual
CPUs in each virtual
core.
sockets integer 1 The number of virtual
sockets.
memory.size string 256M Guest physical memory
size. The size argument
may be suffixed with one
of K, M, G or T (either
upper or lower case) to
indicate a multiple of
kibibytes, mebibytes,
gibibytes, or tebibytes.
If no suffix is given,
the value is assumed to
be in mebibytes.
memory.wired bool false Wire guest memory.
bootrom path Path to a boot ROM.
During initialization of
the guest, the contents
of this file are copied
into the guest's memory.
If a boot ROM is present,
a firmware interface
device is also enabled
for use by the boot ROM.
bootvars path Path to boot VARS. The
contents of this file are
copied beneath the boot
ROM. Firmware can write
to it to save variables.
Variables will be
persistent across guest
reboots.
acpi_tables bool false Generate ACPI tables.
acpi_tables_in_memory bool true bhyve(8) always exposes
ACPI tables by FwCfg.
For backward
compatibility bhyve
copies them into the
guest memory as well.
This can cause problems
if the guest uses the in-
memory version, since
certain advanced
features, such as TPM
emulation, are exposed
only via FwCfg.
Therefore, it is
recommended to set this
flag to false when
running Windows guests.
destroy_on_poweroff bool false Destroy the VM on guest-
initiated power-off.
gdb.address string localhost Hostname, IP address, or
IPv6 address for the
debug server.
gdb.port integer 0 TCP port number for the
debug server. If this is
set to a non-zero value,
a debug server will
listen for connections on
this port.
gdb.wait bool false If the debug server is
enabled, wait for a
debugger to connect
before starting the
guest.
keyboard.layout string Specify the keyboard
layout name with the file
name in
/usr/share/bhyve/kbdlayout.
This value only works
when loaded with UEFI
mode for VNC, and when a
VNC client that doesn't
support the QEMU Extended
Key Event Message us
used.
pci.enable_bars bool Enable and map PCI BARs
before executing any
guest code. This setting
is true by default but
can be disabled to work
around problems with
guests that remap BARs
themselves (e.g. u-boot).
tpm.path string Path to the host TPM
device. This is
typically /dev/tpm0.
tpm.type string Type of the TPM device
passed to the guest.
Currently, only
"passthru" is supported.
tpm.version string 2.0 Version of the TPM device
according to the TCG
specification.
Currently, only version
2.0 is supported.
rtc.use_localtime bool true The real time clock uses
the local time of the
host. If this is set to
false, the real time
clock uses UTC.
uuid string The universally unique
identifier (UUID) to use
in the guest's System
Management BIOS System
Information structure.
If an explicit value is
not set, a valid UUID is
generated from the host's
hostname and the VM name.
virtio_msix bool true Use MSI-X interrupts for
PCI VirtIO devices. If
set to false, MSI
interrupts are used
instead.
config.dump bool false If this value is set to
true then, after parsing
command line options,
bhyve(8) will write all
of its configuration
variables to stdout and
exit. No VM will be
started.
privileges.debug bool false Enable debug messages
relating to privilege
management. These
messages are sent to
stdout.
rfb.debug bool false Enable debug messages
relating to the RFB (VNC)
server.
viona.debug bool false Enable debug messages
relating to the
accelerated virtio
network device. These
messages are sent to
stdout.
xhci.debug bool false Enable debug messages
relating to the emulated
XHCI (USB) controller.
These messages are sent
to stderr.
bios.vendor string BHYVE This value is used for
the guest's System
Management BIOS System
Information structure.
bios.version string 14.0 This value is used for
the guest's System
Management BIOS System
Information structure.
bios.release_date string 10/17/2021 This value is used for
the guest's System
Management BIOS System
Information structure.
system.family_name string Virtual Machine
Family the computer
belongs to. This value
is used for the guest's
System Management BIOS
System Information
structure.
system.manufacturer string illumos This value is used for
the guest's System
Management BIOS System
Information structure.
system.product_name string BHYVE This value is used for
the guest's System
Management BIOS System
Information structure.
system.serial_number string None This value is used for
the guest's System
Management BIOS System
Information structure.
system.sku string None Stock keeping unit of the
computer. It's also
called product ID or
purchase order number.
This value is used for
the guest's System
Management BIOS System
Information structure.
system.version string 1.0 This value is used for
the guest's System
Management BIOS System
Information structure.
board.manufacturer string illumos This value is used for
the guest's System
Management BIOS System
Information structure.
board.product_name string BHYVE This value is used for
the guest's System
Management BIOS System
Information structure.
board.version string 1.0 This value is used for
the guest's System
Management BIOS System
Information structure.
board.serial_number string None This value is used for
the guest's System
Management BIOS System
Information structure.
board.asset_tag string None This value is used for
the guest's System
Management BIOS System
Information structure.
board.location string None Describes the board's
location within the
chassis. This value is
used for the guest's
System Management BIOS
System Information
structure.
chassis.manufacturer string illumos This value is used for
the guest's System
Management BIOS System
Information structure.
chassis.version string 1.0 This value is used for
the guest's System
Management BIOS System
Information structure.
chassis.serial_number string None This value is used for
the guest's System
Management BIOS System
Information structure.
chassis.asset_tag string None This value is used for
the guest's System
Management BIOS System
Information structure.
chassis.sku string None Stock keeping unit of the
chassis. It's also
called product ID or
purchase order number.
This value is used for
the guest's System
Management BIOS System
Information structure.
smbios.family string Virtual Machine
Legacy alias for
system.family_name, do
not use in new
configurations.
smbios.manufacturer string illumos Legacy alias for
system.manufacturer, do
not use in new
configurations.
smbios.product string BHYVE Legacy alias for
system.product_name, do
not use in new
configurations.
smbios.serial string None Legacy alias for
system.serial_number, do
not use in new
configurations.
smbios.sku string None Legacy alias for
system.sku, do not use in
new configurations.
smbios.version string 1.0 Legacy alias for
system.version, do not
use in new
configurations.

x86-Specific Settings
Name Format Default Description
x86.mptable bool true Generate an MPTable.
x86.x2apic bool false Configure guest's local
APICs in x2APIC mode.
x86.strictio bool false Exit if a guest accesses
an I/O port that is not
emulated. By default,
writes are ignored and
reads return all bits set.
x86.strictmsr bool true Inject a general
protection fault if a
guest accesses a Model
Specific Register (MSR)
that is not emulated. If
this is false, writes are
ignored and reads return
zero.
x86.vmexit_on_hlt bool false Force a VM exit when a
guest CPU executes the HLT
instruction. This allows
idle guest CPUs to yield
the host CPU.
x86.vmexit_on_pause bool false Force a VM exit when a
guest CPU executes the
PAUSE instruction.

DEVICE SETTINGS

Device settings are stored under a device node. The device node's name
is set by the parent bus of the device.

PCI Device Settings

PCI devices are described by a device node named
"pci.bus.slot.function" where each of bus, slot, and function are
formatted as decimal values with no padding. All PCI device nodes must
contain a configuration variable named "device" which specifies the
device model to use. The following PCI device models are supported:

hostbridge
Provide a simple PCI-Host bridge device. This is usually
configured at pci0:0:0 and is required by most guest operating
systems.

ahci AHCI storage controller.

e1000 Intel e82545 network interface.

fbuf VGA framebuffer device attached to VNC server.

lpc LPC PCI-ISA bridge with COM1-COM4 16550 serial ports, a boot
ROM, an optional fwcfg type, and an optional debug/test device.
This device must be configured on bus 0.

nvme NVM Express (NVMe) controller.

passthru
PCI pass-through device.

uart PCI 16550 serial device.

virtio-9p
VirtIO 9p (VirtFS) interface.

virtio-blk
VirtIO block storage interface.

virtio-console
VirtIO console interface.

virtio-net-viona
Accelerated VirtIO network interface.

net-viona
Legacy VirtIO network interface.

virtio-rnd
VirtIO random number generator interface.

xhci Extensible Host Controller Interface (XHCI) USB controller.

USB Device Settings

USB controller devices contain zero or more child USB devices attached
to slots. Each USB device stores its settings in a node named "slot.N"
under the controller's device node. N is the number of the slot to
which the USB device is attached. Note that USB slot numbers begin at
1. All USB device nodes must contain a configuration variable named
"device" which specifies the device model to use. The following USB
device models are supported:

tablet A USB tablet device which provides precise cursor
synchronization when using VNC.

Block Device Settings

Block devices use the following settings to configure their backing
store. These settings are stored in the configuration node of the
respective device.

Name Format Default Description
path string The path of the file or
disk device to use as
the backing store.
nocache bool false Disable caching on the
backing file by opening
the backing file with
O_DIRECT.
nodelete bool false Disable emulation of
guest trim requests via
DIOCGDELETE requests.
sync bool false Write changes to the
backing file with
synchronous writes.
direct bool false An alias for sync.
ro bool false Disable writes to the
backing file.
sectorsize logical[/physical] Specify the logical and
physical sector size of
the emulated disk. If
the physical size is not
specified, it is set to
be equal to the logical
size.

virtio-net-viona Network Backend Settings
Viona network devices use the following settings to configure their
backend.

Name Format Default Description
vnic string The VNIC to use for the network
connection.
feature_mask integer 0 Specify a mask to apply to the
virtio features advertised to the
guest.

Viona network devices have the ability to lend out their TX buffers,
which can occasionally cause issues if they are not returned. This
will result in the guest not being able to send any network packets,
including TCP ACKs, resulting in the guest becoming completely
unreachable. The default has changed to now always copy TX buffers. A
temporary tunable has been added (which will be removed when this has
been properly addressed) to restore the ability for the driver to loan
out TX buffers, which is enabled by setting the variable
viona:viona_default_tx_copy to 0 in system(5).

Other Network Backend Settings

Other network devices use the following settings to configure their
backend.

Name Format Default Description
vnic string The VNIC to use for the network
connection.
promiscphys bool false Enable promiscuous mode at the
physical level.
promiscsap bool true Enable promiscuous mode at the
SAP level.
promiscmulti bool true Enable promiscuous mode for all
multicast addresses.
promiscrxonly bool true The selected promiscuous modes
are only enabled for received
traffic.

UART Device Settings

Name Format Default Description
path path Backend device for the serial port.
Either the pathname of a character device
or "stdio" to use standard input and
output of the bhyve(8) process.

Host Bridge Settings

Host Bridge devices use the following settings. When configuring
parameters, either the model by itself, or both of vendor and devid
must be specified. The vendor and device IDs can be specified using
the legacy vendor and devid, or via the new pcireg.vendor and
pcireg.device properties.

Name Format Default Description
model string netapp Specify a hostbridge model to
emulate. Valid model strings, and
their associated vendor and device
IDs are: amd (0x1022/0x7432), netapp
(0x1275/0x1275), i440fx
(0x8086/0x1237) and q35
(0x8086/0x29b0).
vendor integer 0x1275 PCI vendor ID.
devid integer 0x1275 PCI device ID.
pcireg.* integer Values of PCI register.

Name Type Default
vendor integer 0x1275
device integer 0x1275

AHCI Controller Settings

AHCI controller devices contain zero or more ports each of which
provides a storage device. Each port stores its settings in a node
named "port.N" under the controller's device node. The N values are
formatted as successive decimal values starting with 0. In addition to
the block device settings described above, each port supports the
following settings:

Name Format Default Description
type string The type of storage device to emulate.
Must be set to either "cd" or "hd".
nmrr integer 0 Nominal Media Rotation Rate, also
known as RPM. A value 1 of indicates
a device with no rate such as a Solid
State Disk.
ser string generated Serial number of up to twenty
characters. A default serial number
is generated using a hash of the
backing store's pathname.
rev string 001 Revision number of up to eight
characters.
model string Model number of up to forty
characters. Separate default model
strings are used for "cd" and "hd"
device types.

Frame Buffer Settings

Name Format Default Description
wait bool false Wait for a remote connection
before starting the VM.
rfb [IP:]port 127.0.0.1:5900 TCP address to listen on for
remote connections. The IP
address must be given as a
numeric address. IPv6
addresses must be enclosed
in square brackets and
support scoped identifiers
as described in
getaddrinfo(3SOCKET). A
bare port number may be
given in which case the IPv4
localhost address is used.
unix string UNIX socket to listen on for
VNC connections.
vga string io VGA configuration. More
details are provided in
bhyve(8).
w integer 1024 Frame buffer width in
pixels.
h integer 768 Frame buffer height in
pixels.
password string Password to use for VNC
authentication. This type
of authentication is known
to be cryptographically weak
and is not intended for use
on untrusted networks.

LPC Device Settings

The LPC bridge stores its configuration under a top-level lpc node
rather than under the PCI LPC device's node. The following nodes are
available under lpc:

Name Format Default Description
com1 node Settings for the COM1 serial port
device.
com2 node Settings for the COM2 serial port
device.
com3 node Settings for the COM3 serial port
device.
com4 node Settings for the COM4 serial port
device.
fwcfg string bhyve The fwcfg type to be used.
Supported values are "bhyve" for
fwctl and "qemu" for fwcfg.
pc-testdev bool false Enable the PC debug/test device.
pcireg.* integer Values of PCI register. This value
is required for the Intel GOP driver
to work properly.

Name Default
vendor 0x8086
device 0x7000
revid 0
subvendor 0
subdevice 0

NVMe Controller Settings

Each NVMe controller supports a single storage device. The device can
be backed either by a memory disk described by the ram variable, or a
block device using the block device settings described above. In
addition, each controller supports the following settings:

Name Format Default Description
maxq integer 16 Maximum number of I/O submission and
completion queue pairs.
qsz integer 2058 Number of elements in each I/O queue.
ioslots integer 8 Maximum number of concurrent I/O
requests.
sectsz integer Sector size. Can be one of 512, 4096,
or 8192. Devices backed by a memory
disk use 4096 as the default. Devices
backed by a block device use the block
device's sector size as the default.
ser string Serial number of up to twenty
characters. A default serial number is
generated using a hash of the device's
PCI address.
eui64 integer IEEE Extended Unique Identifier. If an
EUI is not provided, a default is
generated using a checksum of the
device's PCI address.
dsm string auto Whether or not to advertise Dataset
Management (DSM) support. One of
"auto", "enable", or "disable". The
"auto" setting only advertises support
if the backing store supports resource
freeing, for example via TRIM.
ram integer If set, allocate a memory disk as the
backing store. The value of this
variable is the size of the memory disk
in megabytes.

PCI Passthrough Settings

Name Format Default Description
path string Path to a PCI passthrough device in the
form /dev/pptN where N is the device
number.
rom path ROM file of the device which will be
executed by OVMF to initialise the
device.

VirtIO 9p Settings
Each VirtIO 9p device exposes a single filesystem from a host path.

Name Format Default Description
sharename string The share name exposed to the guest.
path path The path of a directory on the host
to export to the guest.
ro bool false If true, the guest filesystem is
read-only.

VirtIO Block Device Settings

In addition to the block device settings described above, each VirtIO
block device supports the following settings:

Name Format Default Description
ser string generated Serial number of up to twenty
characters. A default serial number
is generated using a hash of the
backing store's pathname.

VirtIO Console Device Settings

Each VirtIO Console device contains one or more console ports. Each
port stores its settings in a node named "port.N" under the
controller's device node. The N values are formatted as successive
decimal values starting with 0. Each port supports the following
settings:

Name Format Default Description
name string The name of the port exposed to the guest.
path path The path of a UNIX domain socket providing
the host connection for the port.