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; these
tables are not used on
illumos.
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.
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.

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

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.

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.

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.
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.
pc-testdev bool false Enable the PC debug/test device.

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.

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)

OmniOS February 26, 2022 OmniOS