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:

true
on
yes
1

The following values may be used to indicate false:

false
off
no
0

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

GLOBAL SETTINGS

Architecture Neutral Settings

Name	Format	Default	Description
name	string
cpus	integer	1
cores	integer	1
threads	integer	1
sockets	integer	1
memory.guest_in_core	bool	false
memory.size	string	256M
memory.wired	bool	false
bootrom	path
bootvars	path
acpi_tables	bool	true
acpi_tables_in_memory	bool	true
destroy_on_poweroff	bool	false
gdb.address	string	localhost
gdb.port	integer	0
gdb.wait	bool	false
keyboard.layout	string
pci.enable_bars	bool
rtc.use_localtime	bool	true
uuid	string
virtio.msix	bool	true
config.dump	bool	false
bios.vendor	string	BHYVE
bios.version	string	14.0
bios.release_date	string	10/17/2021
system.family_name	string	Virtual Machine
system.manufacturer	string	FreeBSD
system.product_name	string	BHYVE
system.serial_number	string	None
system.sku	string	None
system.version	string	1.0
board.manufacturer	string	FreeBSD
board.product_name	string	BHYVE
board.version	string	1.0
board.serial_number	string	None
board.asset_tag	string	None
board.location	string	None
chassis.manufacturer	string	FreeBSD
chassis.version	string	1.0
chassis.serial_number	string	None
chassis.asset_tag	string	None
chassis.sku	string	None
oemstring.N	string	none
rundir	String	/var/run/bhyve/
monitor.enabled	bool	false
monitor.no_reboot	bool	false
vcpu.N.cpuset	string	none

x86-Specific Settings

Name	Format	Default	Description
x86.mptable	bool	true
x86.x2apic	bool	false
x86.strictio	bool	false
x86.strictmsr	bool	true
x86.verbosemsr	bool	false
x86.vmexit_on_hlt	bool	false
x86.vmexit_on_pause	bool	false
domains.N.size	string
domains.N.cpus	string
domains.N.domain_policy	string

arm64 and RISC-V Specific Settings

Name	Format	Default	Description
console	string

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, optionally, a TPM module, a fw_cfg type, and a debug/test device. This device must be configured on bus 0.
hda: High Definition audio controller.
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-input: VirtIO input interface.
virtio-net: VirtIO network interface.
virtio-rnd: VirtIO RNG interface.
virtio-scsi: VirtIO SCSI 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
nocache	bool	false
nodelete	bool	false
sync	bool	false
direct	bool	false
ro	bool	false
sectorsize	logical[/physical]

Network Backend Settings

Network devices use the following settings to configure their backend. The backend is responsible for passing packets between the device model and a desired destination. Configuring a backend requires setting the backend variable. The type of a backend can either be set explicitly via the type variable or it can be inferred from the value of backend.

The following types of backends are supported:

tap: Use the tap(4) interface named in backend as the backend.
netgraph: Use a netgraph(4) socket hook as the backend. This backend uses the following additional variables:

Name Format Default Description

path string

peerhook string

socket string

hook string vmlink
netmap: Use netmap(4) either on a network interface or a port on a vale(4) bridge as the backend. The value of backend is passed to nm_open to connect to a netmap port.
slirp: Use the slirp backend to provide a userspace network stack. The hostfwd variable is used to configure how packets from the host are translated before being sent to the guest.

Name Format Default Description

hostfwd string

If type is not specified explicitly, then it is inferred from backend based on the following patterns:

Pattern	Type
tapN	tap
vmnetN	tap
netgraph	netgraph
netmap:interface	netmap
valebridge:port	netmap

UART Device Settings

Name	Format	Default	Description
path	path
tcp

Host Bridge Settings

Name	Format	Default	Description
pcireg.*	integer

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
nmrr	integer	0
ser	string	generated
rev	string	001
model	string

e1000 Settings

In addition to the network backend settings, Intel e82545 network interfaces support the following variables:

Name	Format	Default	Description
mac	MAC address	generated

Frame Buffer Settings

Name	Format	Default	Description
wait	bool	false
rfb
rfb
vga	string	io
w	integer	1024
h	integer	768
password	string

High Definition Audio Settings

Name	Format	Default	Description
play	path
rec	path

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
com2	node
com3	node
com4	node
fwcfg	string	bhyve
pc-testdev	bool	false
pcireg.*	integer

TPM Device Settings

The TPM device stores its configuration under a top-level tpm node rather than under the LPC TPM device's node. Only one TPM device is supported. The following nodes are available under tpm:

Name	Format	Default	Description
tpm.path	string
tpm.type	string
tpm.version	string	2.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
qsz	integer	2058
ioslots	integer	8
sectsz	integer
ser	string
eui64	integer
dsm	string	auto
ram	integer

PCI Passthrough Settings

The ppt(4) device driver must be attached to the PCI device being passed through. The device to pass through can be identified either by name or its host PCI bus location.

Name	Format	Default	Description
bus	integer
slot	integer
func	integer
pptdev	string
rom	path

VirtIO 9p Settings

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

Name	Format	Default	Description
sharename	string
path	path
ro	bool	false

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

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

VirtIO Input Interface Settings

Each VirtIO Input device contains one input event device. All input events of the input event device are send to the guest by VirtIO Input interface. VirtIO Input Interfaces support the following variables:

Name	Format	Default	Description
path	path

VirtIO Network Interface Settings

In addition to the network backend settings, VirtIO network interfaces support the following variables:

Name	Format	Default	Description
mac	MAC address	generated
mtu	integer	1500

VirtIO SCSI Settings

Name	Format	Default	Description
backend	string	ctl
ctl_ringsz	integer	64
evt_ringsz	integer	64
req_ringsz	integer	64
num_queues	integer	1
seg_max	integer	64
thr_per_q	integer	16
target	[ID:]path	/dev/cam/ctl

The target variable may be specified multiple times with different path arguments to configure multiple distinct SCSI targets. If not explicitly configured, the target IDs will be assigned sequentially beginning with the highest target ID configured so far, or 0 for the first target configured. The target IDs must be unique within each virtio-scsi instance.

The meaning of the path argument is specific to each backend:

Backend	Path	Description
ctl	/dev/cam/ctl[pp.vp]

The following backend-specific variables are supported for VirtIO SCSI:

Backend	Name	Format	Default	Description
ctl	iid	integer	0