BHYVE_CONFIG(5)

📦

version 15.1 · 2 versions

15.1 · freebsd 15.1 (latest)
14.5 · freebsd 14.5

🦋 NAME 🦋

okay so bestie, this is the bhyve_config(5) page from the File Formats Manual — it's all about bhyve_config: bhyve configuration variables. periodt. 💅

✨ 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 — plot twist — 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. no cap, that's the moment. 🌸

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 interpreted as an integer. For those variables, any syntax supported by strtol(3) may be used. 🧚

🌍 GLOBAL SETTINGS 🌍

🧸 Architecture Neutral Settings 🧸

okay bestie, these are the global knobs that don't care what architecture you're running, and they are everything when you're setting up a VM. Each one is a config key, so keep the names exactly as written, mwah 💅

name — string, default: nothing listed. The name of the VM. Give her a name, she deserves one 🎀
cpus — integer, default: 1. The total number of virtual CPUs.
cores — integer, default: 1. The number of virtual cores in each virtual socket.
threads — integer, default: 1. The number of virtual CPUs in each virtual core.
sockets — integer, default: 1. The number of virtual sockets.
memory.guest_in_core — bool, default: false. Include guest memory in the core file.
memory.size — string, default: 256M. Guest physical memory size in bytes. The value must be formatted as described in expand_number(3) 📏
memory.wired — bool, default: false. Wire guest memory.
bootrom — path, default: nothing listed. 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. very demure, very firmware ✨
bootvars — path, default: nothing listed. Path to boot VARS. The contents of this file are copied beneath the boot ROM. Firmware can write to it to save variables. All variables will be persistent even on reboots of the guest.
acpi_tables — bool, default: true. Generate ACPI tables.
acpi_tables_in_memory — bool, default: true. bhyve(8) always exposes ACPI tables by fw_cfg. 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 fw_cfg. Therefore, it is recommended to set this flag to false when running Windows guests 👀
destroy_on_poweroff — bool, default: false. Destroy the VM on guest-initiated power-off.
gdb.address — string, default: localhost. Hostname, IP address, or IPv6 address for the debug server.
gdb.port — integer, default: 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, default: false. If the debug server is enabled, wait for a debugger to connect before starting the guest.
keyboard.layout — string, default: nothing listed. 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 used a VNC client that don't support QEMU Extended Key Event Message (e.g. TightVNC).
pci.enable_bars — bool, default: not one fixed value. Enable and map PCI BARs before executing any guest code. This setting is false by default when using a boot ROM and true otherwise.
rtc.use_localtime — bool, default: 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, default: nothing listed. 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, default: true. Use MSI-X interrupts for PCI VirtIO devices. If set to false, MSI interrupts are used instead.
config.dump — bool, default: false. If this value is set to true after bhyve(8) has finished parsing command line options, then bhyve(8) will write all of its configuration variables to stdout and exit. No VM will be started. periodt, she said what she said 💀
bios.vendor — string, default: BHYVE. This value is used for the guest's System Management BIOS System Information structure.
bios.version — string, default: 14.0. This value is used for the guest's System Management BIOS System Information structure.
bios.release_date — string, default: 10/17/2021. This value is used for the guest's System Management BIOS System Information structure.
system.family_name — string, default: Virtual Machine. Family the computer belongs to. This value is used for the guest's System Management BIOS System Information structure.
system.manufacturer — string, default: FreeBSD. This value is used for the guest's System Management BIOS System Information structure.
system.product_name — string, default: BHYVE. This value is used for the guest's System Management BIOS System Information structure.
system.serial_number — string, default: None. This value is used for the guest's System Management BIOS System Information structure.
system.sku — string, default: 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, default: 1.0. This value is used for the guest's System Management BIOS System Information structure.
board.manufacturer — string, default: FreeBSD. This value is used for the guest's System Management BIOS System Information structure.
board.product_name — string, default: BHYVE. This value is used for the guest's System Management BIOS System Information 🫶
board.version — string, default 1.0. Feeds the guest's System Management BIOS System Information structure. 🧾
board.serial_number — string, default None. Same deal: it goes in the guest's System Management BIOS System Information structure.
board.asset_tag — string, default None. Yep, also the guest's System Management BIOS System Information structure.
board.location — string, default None. Describes where the board sits inside the chassis, and — say it with me — this value is used for the guest's System Management BIOS System Information structure. 📍
chassis.manufacturer — string, default FreeBSD. Goes into the guest's System Management BIOS System Information structure. 🏭
chassis.version — string, default 1.0. Into the guest's System Management BIOS System Information structure it goes.
chassis.serial_number — string, default None. Guest's System Management BIOS System Information structure. You know the drill bestie. 💅
chassis.asset_tag — string, default None. System Management BIOS System Information structure, guest edition.
chassis.sku — string, default None. Stock keeping unit of the chassis — it's also called product ID or purchase order number, iykyk. And (last time, promise) this value is used for the guest's System Management BIOS System Information structure. 🏷️

✨ x86-Specific Settings ✨

Okay so this is the x86 flavour pack, bestie — every knob below is <italic>format</italic>, <italic>default</italic>, what it does 💖

x86.mptable — bool, default true. Generate an MPTable.
x86.x2apic — bool, default false. Configure the guest's local APICs in x2APIC mode.
x86.strictio — bool, default 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. 😤 (strict mode is strict)
x86.strictmsr — bool, default 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.verbosemsr — bool, default false. Enable verbose MSR print out. When this option is true, messages related to reading from (rdmsr) and writing to (wrmsr) MSRs on virtual CPUs will be printed out. This can be useful for debugging purposes. ngl this is the "let me see everything" button 🐛
x86.vmexit_on_hlt — bool, default 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, default false. Force a VM exit when a guest CPU executes the PAUSE instruction.

🎀 DEVICE SETTINGS 🎀

So device settings live under a device node, and the node's name is set by the parent bus of the device. Cute little hierarchy, no cap. 🗂️

🌈 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 (so like, no zero-padding, bestie — don't get fancy). Every single PCI device node must contain a configuration variable named device which specifies the device model to use. Here's the roster of supported PCI device models 👑:

hostbridge — Provide a simple PCI-Host bridge device. This is usually configured at pci0:0:0 and is required by most guest operating systems. Basically the main character of the PCI world. 🫶
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, where N is the number of the slot the USB device is attached to. Heads up though: USB slot numbers begin at 1. 🚨 Every USB device node must contain a configuration variable named device which specifies the device model to use. The supported USB device models are:

tablet — A USB tablet device which provides precise cursor synchronization when using VNC. 🖱️✨

🍓 Block Device Settings

Block devices use the settings below to configure their backing store, and these live in the configuration node of the respective device. 💾

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

🧚 Network Backend Settings

Network devices use the settings below to configure their backend. The backend is the one responsible for passing packets between the device model and a desired destination — think of it as the group-chat relay bestie. 📨 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 (she's flexible like that 💅).

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 these additional variables:
- path — string, no default. The name of the netgraph(4) destination node.
- peerhook — string, no default. The name of the destination hook.
- socket — string, no default. The name of the created ng_socket(4) node.
- hook — string, default vmlink. The name of the source hook on the created ng_socket(4) node.
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. 🔁
hostfwd — format: string, no default. It's a semicolon-separated list of host forwarding rules, and each rule looks like proto:haddr:hport-gaddr:gport, where proto is either tcp or udp. And here's the cute part: if the guest address is equal to the empty string, packets get forwarded to the first DHCP-assigned address in the guest. 💫

If type isn't specified explicitly, it gets inferred from backend based on these patterns, bestie:

tapN → tap
vmnetN → tap
netgraph → netgraph
netmap:interface → netmap
valebridge:port → netmap

🎀 UART Device Settings 🎀

path — format: path, no default. This is the backend device for the serial port. It's either the pathname of a character device, or stdio to use the standard input and output of the bhyve(8) process. Classic either/or, iconic behavior. ✨
tcp — format: [IP:]port, no default. TCP address to listen on for remote connections. The IP address must be given as a numeric address (no names, she's picky 💅). IPv6 addresses must be enclosed in square brackets and supports scoped identifiers as described in getaddrinfo(3).

🌸 Host Bridge Settings 🌸

pcireg.* — format: integer, no default. Values of PCI register. The lineup:
- vendor — integer — default 0x1275
- device — integer — default 0x1275

💜 AHCI Controller Settings 💜

Okay so AHCI controller devices contain zero or more ports, and each one provides a storage device. Every port stores its settings in a node named port.N under the controller's device node — and the N values are formatted as successive decimal values starting with 0. So port.0, port.1, port.2, you get it. 🦋

On top of the block device settings described above, each port supports these:

type — format: string, no default. The type of storage device to emulate. Must be set to either cd or hd. No third option, she said what she said. 😤
nmrr — format: integer, default 0. Nominal Media Rotation Rate, also known as RPM. A value 1 of indicates that the device is a solid state drive, i.e, non-rotational. (That's literally how the manpage says it — "a value 1 of indicates" — I'm not touching it, it's part of the lore now 💀)
ser — format: string, default: generated. Serial number of up to twenty characters. A default serial number is generated using a hash of the backing store's pathname. She makes her own, she doesn't need you. ✨
rev — format: string, default 001. Revision number of up to eight characters.
model — format: string, no default. Model number of up to forty characters. Separate default model strings are used for cd and hd device types — so they don't even share a default, very independent of them. 🫶

🌈 e1000 Settings 🌈

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

mac — format: MAC address, default: generated. The MAC address. If you don't specify it, the MAC address is derived from a fixed OUI, and the remaining bytes from an MD5 hash of the slot and function numbers and the device name. If you do specify it, it must be a unicast MAC address. No funny business. 🔥

🖼️ Frame Buffer Settings 🖼️

wait — format: bool, default false. Wait for a remote connection before starting the VM. She'll wait for you, bestie. 🥺
rfb — format: [IP:]port, default 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(3). A bare port number may be given, in which case the IPv4 localhost address is used. Convenient fr fr.
rfb — format: unix:my/unix.sock, no default. Alternatively, provide a path to a UNIX domain socket. Yes, rfb shows up twice — she contains multitudes. 💅
vga — format: string, default io. VGA configuration. More details are provided in bhyve(8) — go read that one too, I'm serious. 👀
w — format: integer, default 1024. Frame buffer width in pixels.
h — format: integer, default 768. Frame buffer height in pixels.
password — format: string, no default. Password to use for VNC authentication.

⚠️ Heads up: this type of authentication is known to be cryptographically weak and is not intended for use on untrusted networks. I'm not being dramatic, that's literally in the manpage — do not take this to a coffee shop wifi. 💀

🎧 High Definition Audio Settings 🎧

play — format: path, no default. Host playback device, typically /dev/dsp0.
rec — format: path, no default. Host recording device, typically /dev/dsp0.

Both start at /dev/dsp0, so yes, playback and recording are matching. Couple goals honestly. 🎀

🧚 LPC Device Settings 🧚

Small plot twist: the LPC bridge stores its configuration under a top-level lpc node rather than under the PCI LPC device's node. (Not like the others, she's built different. Periodt.) These nodes are available under lpc:

com1 — format: node, no default. Settings for the COM1 serial port device.
com2 — format: node, no default. Settings for the COM2 serial port device.
com3 — format: node, no default. Settings for the COM3 serial port device.
com4 — format: node, no default. Settings for the COM4 serial port device.
fwcfg — format: string, default bhyve. The fw_cfg type to be used. Supported values are bhyve for fwctl and qemu for fw_cfg. Pick your fighter. ⚔️
pc-testdev — format: bool, default false. Enable the PC debug/test device.
pcireg.* — format: integer, no default. Values of PCI register. It also accepts the value host to use the pci id of the host system. This value is required for the Intel GOP driver to work properly — so if the graphics are acting up, this is your girl. 🫶 The registers:
- vendor — default 0x8086
- device — default 0x7000
- revid — default 0
- subvendor — default 0
- subdevice — default 0

🔐 TPM Device Settings 🔐

Same energy as LPC: 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 — one and only one, she's monogamous like that. 💜 Available under tpm:

tpm.path — format: string, no default. Path to the TPM backend. Depending on the tpm.type, this is either the host TPM device, typically /dev/tpm0, or any UNIX domain socket on which a swtpm process is listening.
tpm.type — format: string, no default. Type of the TPM device passed to the guest. This can be either passthru to use the host TPM devices, or swtpm to connect to a running swtpm process.
tpm.version — format: string, default 2.0. Version of the TPM device according to the TCG specification. Currently, only version 2.0 is supported — so don't go asking for anything else, it's not happening. 😭

👑 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:

maxq (integer, default: 16) — the max number of I/O submission + completion queue pairs. yes, pairs. it's giving matched-set energy 🔥
qsz (integer, default: 2058) — how many elements live in each I/O queue. 2058, iconic number, no notes.
ioslots (integer, default: 8) — the maximum number of concurrent I/O requests. eight lanes, don't clog them 😭
sectsz (integer, no default) — the sector size. it can literally only be one of 512, 4096, or 8192. devices backed by a memory disk default to 4096; devices backed by a block device just steal the block device's own sector size as their default. lowkey flexible like that 💅
ser (string, no default) — the serial number, up to twenty characters bestie. and if you don't give one? a default serial number gets generated using a hash of the device's PCI address. it makes its own ✨
eui64 (integer, no default) — the IEEE Extended Unique Identifier. if no EUI is provided, a default is generated using a checksum of the device's PCI address. again: it handles it 🙌
dsm (string, default: auto) — whether or not to advertise Dataset Management support. must be one of "auto", "enable", or "disable". the "auto" setting only advertises support if the backing store supports resource freeing, for example via TRIM. she checks first, she's polite 🎀
ram (integer, no default) — if set, allocate a memory disk as the backing store. the value of this variable is the size of the memory disk in megabytes. set it and it's ram-disk o'clock 🧚

🌈 PCI Passthrough Settings 🌈

fr fr: the ppt(4) device driver must be attached to the PCI device being passed through. no driver, no passthrough, periodt.

the device you're passing through can be identified either by name or by its host PCI bus location. pick your fighter 💜

bus (integer, no default) — host PCI bus address of the device to pass through.
slot (integer, no default) — host PCI slot address of the device to pass through.
func (integer, no default) — host PCI function address of the device to pass through.
pptdev (string, no default) — name of a ppt(4) device to pass through.
rom (path, no default) — ROM file of the device, which will be executed by OVMF to init the device. OVMF does the little startup ritual 😌

🦋 VirtIO 9p Settings 🦋

each VirtIO 9p device exposes a single filesystem from a host path. one device, one share, that's the rule 🫶

sharename (string, no default) — the share name exposed to the guest.
path (path, no default) — the path of a directory on the host to export to the guest.
ro (bool, default: false) — if true, the guest filesystem is read-only. protect the host files, bestie 🛡️

⭐ VirtIO Block Device Settings ⭐

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

ser (string, default: generated) — serial number of up to twenty characters. a default serial number is generated using a hash of the backing store's pathname. notice that's the pathname, not the PCI address — different hash source, iykyk 👀

🎀 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 — and the N values are formatted as successive decimal values starting with 0. so port.0, port.1, port.2, you get it 💅

each port supports the following settings:

name (string, no default) — the name of the port exposed to the guest.
path (path, no default) — the path of a UNIX domain socket providing the host connection for the port. socket-based connection, very demure 🍓

🌸 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 the VirtIO Input interface. VirtIO Input Interfaces support the following variables:

path (path, no default) — the path of the input event device exposed to the guest.

💖 VirtIO Network Interface Settings 💖

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

mac (MAC address, default: generated) — the MAC address. if not specified, it's derived from a fixed OUI, and the remaining bytes from an MD5 hash of the slot and function numbers and the device name. if specified, it must be a unicast MAC address. no multicast shenanigans, she said what she said 💀
mtu (integer, default: 1500) — the largest supported MTU advertised to the guest. classic 1500, the main character of MTUs 👑

🔥 VirtIO SCSI Settings 🔥

dev (path, no default) — the path of a CAM target layer (CTL) device to export: /dev/cam/ctl[pp.vp]. keep that path exactly as written, bestie, [pp.vp] and all 🫡
iid (integer, default: 0) — initiator ID to use when sending requests to the CTL port.

like, go read these too. they're the supporting cast and honestly they ate 💜

aaaand that's the whole page, bestie — you made it to the end, I'm so proud of you 🥹🎀 this one's from Debian, dated December 26, 2025, and it's the BHYVE_CONFIG(5) page, so if you ever need to double-check a variable you know exactly where to find me. mwah 💋✨

📦 where this page comes from

freebsd 15.1: base 15.1
📜 the page's license: BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms