BHYVE_CONFIG(5) Standards, Environments, and Macros 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.
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.
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
bootrom path Path to a boot ROM. The contents of
this file are copied into the guest's
memory ending just before the 4GB
physical address. If a boot ROM is
present, a firmware interface device is
also enabled for use by the boot ROM.
bootvars path Path to boot variables file. 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.
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.

SEE ALSO


strtoul(3C), getaddrinfo(3SOCKET), bhyve(8)

illumos July 29, 2023 illumos