FreeBSD Manual Pages
BHYVE_CONFIG(5) File Formats Manual 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 configura- tion variables understood by bhyve(8). If additional variables are de- fined, bhyve(8) will ignore them and will not emit errors for unknown vari- ables. However, these additional variables can be referenced by other variables as described below. VARIABLE VALUES Configuration variable values are stored as strings. A configuration vari- able value may refer to one or more other configuration values by name. Instances of the pattern `%(var)' are replaced by the value of the configu- ration 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 indi- cate 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 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 sock- ets. memory.guest_in_core bool false Include guest memory in core file. memory.size string 256M Guest physical memory size in bytes. The value must be formatted as described in ex- pand_number(3). 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 mem- ory. 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 con- tents of this file are copied beneath the boot ROM. Firmware can write to it to save variables. All vari- ables will be persistent even on reboots of the guest. acpi_tables bool true Generate ACPI tables. acpi_tables_in_memory bool true bhyve(8) always exposes ACPI tables by fw_cfg. For back- ward 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 fea- tures, 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 false Destroy the VM on guest-ini- tiated 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 con- nections on this port. gdb.wait bool false If the debug server is en- abled, 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 used a VNC client that don't support QEMU Ex- tended Key Event Message (e.g. TightVNC). pci.enable_bars bool Enable and map PCI BARs be- fore executing any guest code. This setting is false by default when using a boot ROM and true otherwise. 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 iden- tifier (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 after bhyve(8) has finished parsing command line options, then bhyve(8) will write all of its configuration vari- ables to stdout and exit. No VM will be started. 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 MachineFamily the computer be- longs to. This value is used for the guest's System Man- agement BIOS System Informa- tion structure. system.manufacturer string FreeBSD 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 Man- agement BIOS System Informa- tion structure. system.version string 1.0 This value is used for the guest's System Management BIOS System Information structure. board.manufacturer string FreeBSD 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 loca- tion within the chassis. This value is used for the guest's System Management BIOS System Information structure. chassis.manufacturer string FreeBSD 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 Man- agement BIOS System Informa- tion structure. 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.verbosemsr bool false Enable verbose MSR print out. When this option is true, mes- sages related to reading from (rdmsr) and writing to (wrmsr) MSRs on virtual CPUs will be printed out. This can be use- ful for debugging purposes. x86.vmexit_on_hlt bool false Force a VM exit when a guest CPU executes the HLT instruc- tion. 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 in- struction. 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 config- ured 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 de- vice. 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 de- vice. 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 back- ing 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 back- ing file. sectorsize logical[/physical ] Specify the logical and physical sector size of the emulated disk. If the phys- ical size is not specified, it is equal to the logical size. 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 The name of the netgraph(4) des- tination node. peerhook string The name of the destination hook. socket string The name of the created ng_socket(4) node. hook string 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. Name Format Default Description hostfwd string A semicolon-separated list of host forwarding rules, each of the form proto:haddr:hport-gaddr:gport, where proto is either `tcp' or `udp'. If the guest address is equal to the empty string, pack- ets will be forwarded to the first DHCP-assigned address in the guest. 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 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. tcp [IP:]port TCP address to listen on for remote connec- tions. The IP address must be given as a nu- meric address. IPv6 addresses must be en- closed in square brackets and supports scoped identifiers as described in getaddrinfo(3). Host Bridge Settings Name Format Default Description pcireg.* integer Values of PCI register. Name 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" un- der 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 that the de- vice is a solid state drive, i.e, non-ro- tational. 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. e1000 Settings In addition to the network backend settings, Intel e82545 network inter- faces support the following variables: Name Format Default Description mac MAC address generated MAC address. If not specified, 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 specified, it must be a unicast MAC address. Frame Buffer Settings Name Format Default Description wait bool false Wait for a remote con- nection 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 ad- dress. IPv6 addresses must be enclosed in square brackets and sup- port scoped identifiers as described in getad- drinfo(3). A bare port number may be given in which case the IPv4 lo- calhost address is used. rfb unix:my/unix.sock Alternatively, provide a path to a UNIX domain socket. 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 crypto- graphically weak and is not intended for use on untrusted networks. High Definition Audio Settings Name Format Default Description play path Host playback device, typically /dev/dsp0. rec path Host recording device, typically /dev/dsp0. 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 de- vice. com2 node Settings for the COM2 serial port de- vice. com3 node Settings for the COM3 serial port de- vice. com4 node Settings for the COM4 serial port de- vice. fwcfg string bhyve The fw_cfg type to be used. Supported values are "bhyve" for fwctl and "qemu" for fw_cfg. pc-testdev bool false Enable the PC debug/test device. pcireg.* integer 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. Name Default vendor 0x8086 device 0x7000 revid 0 subvendor 0 subdevice 0 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 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 string 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 string 2.0 Version of the TPM device according to the TCG specification. Currently, only version 2.0 is supported. 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 com- pletion 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 us- ing a checksum of the device's PCI address. dsm string auto Whether or not to advertise Dataset Manage- ment support. One of "auto", "enable", or "disable". The "auto" setting only adver- tises support if the backing store supports resource freeing, for example via TRIM. ram integer If set, allocate a memory disk as the back- ing store. The value of this variable is the size of the memory disk in megabytes. 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 Host PCI bus address of device to pass through. slot integer Host PCI slot address of device to pass through. func integer Host PCI function address of device to pass through. pptdev string Name of a ppt(4) device to pass through. rom path ROM file of the device which will be executed by OVMF to init 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. 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 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 sup- port the following variables: Name Format Default Description mac MAC address generated MAC address. If not specified, 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 specified, it must be a unicast MAC address. mtu integer 1500 The largest supported MTU advertised to the guest. VirtIO SCSI Settings Name Format Default Description dev path The path of a CAM target layer (CTL) device to export: /dev/cam/ctl[pp.vp]. iid integer 0 Initiator ID to use when sending requests to the CTL port. SEE ALSO expand_number(3), getaddrinfo(3), strtol(3), netgraph(4), netmap(4), ng_socket(4), tap(4), vale(4), vmnet(4), bhyve(8) FreeBSD ports 15.quarterly December 26, 2025 BHYVE_CONFIG(5)
NAME | DESCRIPTION | VARIABLE VALUES | GLOBAL SETTINGS | DEVICE SETTINGS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=bhyve_config&sektion=5&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>