1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2021 John H. Baldwin <jhb@FreeBSD.org> 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd March 2, 2022 27.Dt BHYVE_CONFIG 5 28.Os 29.Sh NAME 30.Nm bhyve_config 31.Nd "bhyve configuration variables" 32.Sh DESCRIPTION 33.Xr bhyve 8 34uses a hierarchical tree of configuration variables to describe global and 35per-device settings. 36Internal nodes in this tree do not have a value, 37only leaf nodes have values. 38This manual describes the configuration variables understood by 39.Xr bhyve 8 . 40If additional variables are defined, 41.Xr bhyve 8 42will ignore them and will not emit errors for unknown variables. 43However, these additional variables can be referenced by other 44variables as described below. 45.Sh VARIABLE VALUES 46Configuration variable values are stored as strings. 47A configuration variable value may refer to one or more other 48configuration values by name. 49Instances of the pattern 50.Sq % Ns Pq Ar var 51are replaced by the value of the configuration variable 52.Va var . 53To avoid unwanted expansion, 54.Sq % 55characters can be escaped by a leading 56.Sq % . 57For example, 58if a configuration variable 59.Va disk 60uses the value 61.Pa /dev/zvol/bhyve/%(name) , 62then the final value of the 63.Va disk 64variable will be set to the path of a ZFS volume whose name matches 65the name of the virtual machine on the pool 66.Pa bhyve . 67.Pp 68Some configuration variables may be interpreted as a boolean value. 69For those variables the following case-insensitive values may be used to 70indicate true: 71.Pp 72.Bl -bullet -offset indent -compact 73.It 74true 75.It 76on 77.It 78yes 79.It 801 81.El 82.Pp 83The following values may be used to indicate false: 84.Pp 85.Bl -bullet -offset indent -compact 86.It 87false 88.It 89off 90.It 91no 92.It 930 94.El 95.Pp 96Some configuration variables may be interperted as an integer. 97For those variables, 98any syntax supported by 99.Xr strtol 3 100may be used. 101.Sh GLOBAL SETTINGS 102.Ss Architecture Neutral Settings 103.Bl -column "memory.guest_in_core" "integer" "Default" 104.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 105.It Va name Ta string Ta Ta 106The name of the VM. 107.It Va cpus Ta integer Ta 1 Ta 108The total number of virtual CPUs. 109.It Va cores Ta integer Ta 1 Ta 110The number of virtual cores in each virtual socket. 111.It Va threads Ta integer Ta 1 Ta 112The number of virtual CPUs in each virtual core. 113.It Va sockets Ta integer Ta 1 Ta 114The number of virtual sockets. 115.It Va memory.guest_in_core Ta bool Ta false Ta 116Include guest memory in core file. 117.It Va memory.size Ta string Ta 256M Ta 118Guest physical memory size in bytes. 119The value must be formatted as described in 120.Xr expand_number 3 . 121.It Va memory.wired Ta bool Ta false Ta 122Wire guest memory. 123.It Va acpi_tables Ta bool Ta false Ta 124Generate ACPI tables. 125.It Va destroy_on_poweroff Ta bool Ta false Ta 126Destroy the VM on guest-initiated power-off. 127.It Va gdb.address Ta string Ta localhost Ta 128Hostname, IP address, or IPv6 address for the debug server. 129.It Va gdb.port Ta integer Ta 0 Ta 130TCP port number for the debug server. 131If this is set to a non-zero value, a debug server 132will listen for connections on this port. 133.It Va gdb.wait Ta bool Ta false Ta 134If the debug server is enabled, wait for a debugger to connect 135before starting the guest. 136.It Va keyboard.layout Ta string Ta Ta 137Specify the keyboard layout name with the file name in 138.Ar /usr/share/bhyve/kbdlayout . 139This value only works when loaded with UEFI mode for VNC, and 140used a VNC client that don't support QEMU Extended Key Event 141Message (e.g. TightVNC). 142.It Va rtc.use_localtime Ta bool Ta true Ta 143The real time clock uses the local time of the host. 144If this is set to false, the real time clock uses UTC. 145.It Va uuid Ta string Ta Ta 146The universally unique identifier (UUID) to use in the guest's 147System Management BIOS System Information structure. 148If an explicit value is not set, a valid UUID is generated from 149the host's hostname and the VM name. 150.It Va virtio_msix Ta bool Ta true Ta 151Use MSI-X interrupts for PCI VirtIO devices. 152If set to false, MSI interrupts are used instead. 153.It Va config.dump Ta bool Ta false Ta 154If this value is set to true after 155.Xr bhyve 8 156has finished parsing command line options, 157then 158.Xr bhyve 8 159will write all of its configuration variables to stdout and exit. 160No VM will be started. 161.El 162.Ss x86-Specific Settings 163.Bl -column "x86.vmexit_on_pause" "integer" "Default" 164.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 165.It Va x86.mptable Ta bool Ta true Ta 166Generate an MPTable. 167.It Va x86.x2apic Ta bool Ta false Ta 168Configure guest's local APICs in x2APIC mode. 169.It Va x86.strictio Ta bool Ta false Ta 170Exit if a guest accesses an I/O port that is not emulated. 171By default, writes are ignored and reads return all bits set. 172.It Va x86.strictmsr Ta bool Ta true Ta 173Inject a general protection fault if a guest accesses a Model Specific 174Register (MSR) that is not emulated. 175If this is false, writes are ignored and reads return zero. 176.It Va x86.vmexit_on_hlt Ta bool Ta false Ta 177Force a VM exit when a guest CPU executes the 178.Dv HLT 179instruction. 180This allows idle guest CPUs to yield the host CPU. 181.It Va x86.vmexit_on_pause Ta bool Ta false Ta 182Force a VM exit when a guest CPU executes the 183.Dv PAUSE 184instruction. 185.El 186.Sh DEVICE SETTINGS 187Device settings are stored under a device node. 188The device node's name is set by the parent bus of the device. 189.Ss PCI Device Settings 190PCI devices are described by a device node named 191.Dq pci . Ns Ar bus . Ns Ar slot . Ns Ar function 192where each of 193.Ar bus , 194.Ar slot , 195and 196.Ar function 197are formatted as decimal values with no padding. 198All PCI device nodes must contain a configuration variable named 199.Dq device 200which specifies the device model to use. 201The following PCI device models are supported: 202.Bl -tag -indent 203.It Li hostbridge 204Provide a simple PCI-Host bridge device. 205This is usually configured at pci0:0:0 and is required by most guest 206operating systems. 207.It Li ahci 208AHCI storage controller. 209.It Li e1000 210Intel e82545 network interface. 211.It Li fbuf 212VGA framebuffer device attached to VNC server. 213.It Li lpc 214LPC PCI-ISA bridge with COM1-COM4 16550 serial ports, 215a boot ROM, 216and an optional debug/test device. 217This device must be configured on bus 0. 218.It Li hda 219High Definition audio controller. 220.It Li nvme 221NVM Express (NVMe) controller. 222.It Li passthru 223PCI pass-through device. 224.It Li uart 225PCI 16550 serial device. 226.It Li virtio-9p 227VirtIO 9p (VirtFS) interface. 228.It Li virtio-blk 229VirtIO block storage interface. 230.It Li virtio-console 231VirtIO console interface. 232.It Li virtio-input 233VirtIO input interface. 234.It Li virtio-net 235VirtIO network interface. 236.It Li virtio-rnd 237VirtIO RNG interface. 238.It Li virtio-scsi 239VirtIO SCSI interface. 240.It Li xhci 241Extensible Host Controller Interface (XHCI) USB controller. 242.El 243.Ss USB Device Settings 244USB controller devices contain zero or more child USB devices 245attached to slots. 246Each USB device stores its settings in a node named 247.Dq slot. Ns Va N 248under the controller's device node. 249.Va N 250is the number of the slot to which the USB device is attached. 251Note that USB slot numbers begin at 1. 252All USB device nodes must contain a configuration variable named 253.Dq device 254which specifies the device model to use. 255The following USB device models are supported: 256.Bl -tag -indent 257.It Li tablet 258A USB tablet device which provides precise cursor synchronization 259when using VNC. 260.El 261.Ss Block Device Settings 262Block devices use the following settings to configure their backing store. 263These settings are stored in the configuration node of the respective device. 264.Bl -column "sectorsize" "logical[/physical]" "Default" 265.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 266.It path Ta string Ta Ta 267The path of the file or disk device to use as the backing store. 268.It nocache Ta bool Ta false Ta 269Disable caching on the backing file by opening the backing file with 270.Dv O_DIRECT . 271.It nodelete Ta bool Ta false Ta 272Disable emulation of guest trim requests via 273.Dv DIOCGDELETE 274requests. 275.It sync Ta bool Ta false Ta 276Write changes to the backing file with synchronous writes. 277.It direct Ta bool Ta false Ta 278An alias for 279.Va sync . 280.It ro Ta bool Ta false Ta 281Disable writes to the backing file. 282.It sectorsize Ta Va logical Ns Op / Ns Va physical Ta Ta 283Specify the logical and physical sector size of the emulated disk. 284If the physical size is not specified, 285it is equal to the logical size. 286.El 287.Ss Network Backend Settings 288Network devices use the following settings to configure their backend. 289The backend is responsible for passing packets between the device model 290and a desired destination. 291Configuring a backend requires setting the 292.Va backend 293variable to one of the following values: 294.Bl -tag 295.It tap Ns Va N 296Use the named 297.Xr tap 4 298interface as the backend. 299.It vmnet Ns Va N 300Use the named 301.Xr vmnet 4 302interface as the backend. 303.It netgraph 304Use a 305.Xr netgraph 4 306socket hook as the backend. 307This backend uses the following additional variables: 308.Bl -column "peerhook" "Format" "Default" 309.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 310.It Va path Ta string Ta Ta 311The name of the 312.Xr netgraph 4 313destination node. 314.It Va peerhook Ta string Ta Ta 315The name of the destination hook. 316.It Va socket Ta string Ta Ta 317The name of the created 318.Xr ng_socket 4 319node. 320.It Va hook Ta string Ta vmlink Ta 321The name of the source hook on the created 322.Xr ng_socket 4 323node. 324.El 325.It netmap: Ns Va interface 326Use 327.Xr netmap 4 328on a network interface as the backend. 329.It vale Ns Va bridge : Ns Va port 330Use a port on a 331.Xr vale 4 332bridge as the backend. 333.El 334.Ss UART Device Settings 335.Bl -column "Name" "Format" "Default" 336.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 337.It Va path Ta path Ta Ta 338Backend device for the serial port. 339Either the pathname of a character device or 340.Dq stdio 341to use standard input and output of the 342.Xr bhyve 8 343process. 344.El 345.Ss Host Bridge Settings 346.Bl -column "vendor" "integer" "Default" 347.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 348.It Va vendor Ta integer Ta 0x1275 Ta 349PCI vendor ID. 350.It Va devid Ta integer Ta 0x1275 Ta 351PCI device ID. 352.El 353.Ss AHCI Controller Settings 354AHCI controller devices contain zero or more ports each of which 355provides a storage device. 356Each port stores its settings in a node named 357.Dq port. Ns Va N 358under the controller's device node. 359The 360.Va N 361values are formatted as successive decimal values starting with 0. 362In addition to the block device settings described above, each 363port supports the following settings: 364.Bl -column "model" "integer" "generated" 365.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 366.It Va type Ta string Ta Ta 367The type of storage device to emulate. 368Must be set to either 369.Dq cd 370or 371.Dq hd . 372.It Va nmrr Ta integer Ta 0 Ta 373Nominal Media Rotation Rate, also known as RPM. 374A value 1 of indicates a device with no rate such as a Solid State Disk. 375.It Va ser Ta string Ta generated Ta 376Serial number of up to twenty characters. 377A default serial number is generated using a hash of the backing 378store's pathname. 379.It Va rev Ta string Ta 001 Ta 380Revision number of up to eight characters. 381.It Va model Ta string Ta Ta 382Model number of up to forty characters. 383Separate default model strings are used for 384.Dq cd 385and 386.Dq hd 387device types. 388.El 389.Ss e1000 Settings 390In addition to the network backend settings, 391Intel e82545 network interfaces support the following variables: 392.Bl -column "Name" "MAC address" "generated" 393.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 394.It Va mac Ta MAC address Ta generated Ta 395MAC address. 396If an explicit address is not provided, 397a MAC address is generated from a hash of the device's PCI address. 398.El 399.Ss Frame Buffer Settings 400.Bl -column "password" "[IP:]port" "127.0.0.1:5900" 401.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 402.It Va wait Ta bool Ta false Ta 403Wait for a remote connection before starting the VM. 404.It Va rfb Ta Oo Ar IP Ns : Oc Ns Ar port Ta 127.0.0.1:5900 Ta 405TCP address to listen on for remote connections. 406The IP address must be given as a numeric address. 407IPv6 addresses must be enclosed in square brackets and 408support scoped identifiers as described in 409.Xr getaddrinfo 3 . 410A bare port number may be given in which case the IPv4 411localhost address is used. 412.It Va vga Ta string Ta io Ta 413VGA configuration. 414More details are provided in 415.Xr bhyve 8 . 416.It Va w Ta integer Ta 1024 Ta 417Frame buffer width in pixels. 418.It Va h Ta integer Ta 768 Ta 419Frame buffer height in pixels. 420.It Va password Ta string Ta Ta 421Password to use for VNC authentication. 422This type of authentication is known to be cryptographically weak and is not 423intended for use on untrusted networks. 424.El 425.Ss High Definition Audio Settings 426.Bl -column "Name" "Format" "Default" 427.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 428.It Va play Ta path Ta Ta 429Host playback device, 430typically 431.Pa /dev/dsp0 . 432.It Va rec Ta path Ta Ta 433Host recording device, 434typically 435.Pa /dev/dsp0 . 436.El 437.Ss LPC Device Settings 438The LPC bridge stores its configuration under a top-level 439.Va lpc 440node rather than under the PCI LPC device's node. 441The following nodes are available under 442.Va lpc : 443.Bl -column "pc-testdev" "Format" "Default" 444.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 445.It Va bootrom Ta path Ta Ta 446Path to a boot ROM. 447The contents of this file are copied into the guest's 448memory ending just before the 4GB physical address. 449If a boot ROM is present, a firmware interface device is 450also enabled for use by the boot ROM. 451.It Va bootvars Ta path Ta Ta 452Path to boot VARS. 453The contents of this file are copied beneath the boot ROM. 454Firmware can write to it to save variables. 455All variables will be persistent even on reboots of the guest. 456.It Va com1 Ta node Ta Ta 457Settings for the COM1 serial port device. 458.It Va com2 Ta node Ta Ta 459Settings for the COM2 serial port device. 460.It Va com3 Ta node Ta Ta 461Settings for the COM3 serial port device. 462.It Va com4 Ta node Ta Ta 463Settings for the COM4 serial port device. 464.It Va pc-testdev Ta bool Ta false Ta 465Enable the PC debug/test device. 466.El 467.Ss NVMe Controller Settings 468Each NVMe controller supports a single storage device. 469The device can be backed either by a memory disk described by the 470.Va ram 471variable, or a block device using the block device settings described above. 472In addition, each controller supports the following settings: 473.Bl -column "ioslots" "Format" "Default" 474.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 475.It Va maxq Ta integer Ta 16 Ta 476Maximum number of I/O submission and completion queue pairs. 477.It Va qsz Ta integer Ta 2058 Ta 478Number of elements in each I/O queue. 479.It Va ioslots Ta integer Ta 8 Ta 480Maximum number of concurrent I/O requests. 481.It Va sectsz Ta integer Ta Ta 482Sector size. 483Can be one of 512, 4096, or 8192. 484Devices backed by a memory disk use 4096 as the default. 485Devices backed by a block device use the block device's sector size 486as the default. 487.It Va ser Ta string Ta Ta 488Serial number of up to twenty characters. 489A default serial number is generated using a hash of the device's PCI address. 490.It Va eui64 Ta integer Ta Ta 491IEEE Extended Unique Identifier. 492If an EUI is not provided, a default is generated using a checksum of the 493device's PCI address. 494.It Va dsm Ta string Ta auto Ta 495Whether or not to advertise DataSet Management support. 496One of 497.Dq auto , 498.Dq enable , 499or 500.Dq disable . 501The 502.Dq auto 503setting only advertises support if the backing store supports 504resource freeing, for example via TRIM. 505.It Va ram Ta integer Ta Ta 506If set, allocate a memory disk as the backing store. 507The value of this variable is the size of the memory disk in megabytes. 508.El 509.Ss PCI Passthrough Settings 510.Bl -column "Name" "integer" "Default" 511.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 512.It Va bus Ta integer Ta Ta 513Host PCI bus address of device to pass through. 514.It Va slot Ta integer Ta Ta 515Host PCI slot address of device to pass through. 516.It Va func Ta integer Ta Ta 517Host PCI function address of device to pass through. 518.It Va rom Ta path Ta Ta 519ROM file of the device which will be executed by OVMF to init the device. 520.El 521.Ss VirtIO 9p Settings 522Each VirtIO 9p device exposes a single filesystem from a host path. 523.Bl -column "sharename" "Format" "Default" 524.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 525.It Va sharename Ta string Ta Ta 526The share name exposed to the guest. 527.It Va path Ta path Ta Ta 528The path of a directory on the host to export to the guest. 529.It Va ro Ta bool Ta false Ta 530If true, the guest filesystem is read-only. 531.El 532.Ss VirtIO Block Device Settings 533In addition to the block device settings described above, each 534VirtIO block device supports the following settings: 535.Bl -column "model" "integer" "generated" 536.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 537.It Va ser Ta string Ta generated Ta 538Serial number of up to twenty characters. 539A default serial number is generated using a hash of the backing 540store's pathname. 541.El 542.Ss VirtIO Console Device Settings 543Each VirtIO Console device contains one or more console ports. 544Each port stores its settings in a node named 545.Dq port. Ns Va N 546under the controller's device node. 547The 548.Va N 549values are formatted as successive decimal values starting with 0. 550Each port supports the following settings: 551.Bl -column "Name" "Format" "Default" 552.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 553.It Va name Ta string Ta Ta 554The name of the port exposed to the guest. 555.It Va path Ta path Ta Ta 556The path of a UNIX domain socket providing the host connection for the port. 557.El 558.Ss VirtIO Input Interface Settings 559Each VirtIO Input device contains one input event device. 560All input events of the input event device are send to the guest by VirtIO Input interface. 561VirtIO Input Interfaces support the following variables: 562.Bl -column "Name" "Format" "Default" 563.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 564.It Va path Ta path Ta Ta 565The path of the input event device exposed to the guest 566.El 567.Ss VirtIO Network Interface Settings 568In addition to the network backend settings, 569VirtIO network interfaces support the following variables: 570.Bl -column "Name" "MAC address" "generated" 571.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 572.It Va mac Ta MAC address Ta generated Ta 573MAC address. 574If an explicit address is not provided, 575a MAC address is generated from a hash of the device's PCI address. 576.It Va mtu Ta integer Ta 1500 Ta 577The largest supported MTU advertised to the guest. 578.El 579.Ss VirtIO SCSI Settings 580.Bl -column "Name" "integer" "Default" 581.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description 582.It Va dev Ta path Ta Ta 583The path of a CAM target layer (CTL) device to export: 584.Pa /dev/cam/ctl Ns Oo Ar pp . Ns Ar vp Oc . 585.It Va iid Ta integer Ta 0 Ta 586Initiator ID to use when sending requests to the CTL port. 587.El 588.Sh SEE ALSO 589.Xr expand_number 3 , 590.Xr getaddrinfo 3 , 591.Xr strtol 3 , 592.Xr netgraph 4 , 593.Xr netmap 4 , 594.Xr ng_socket 4 , 595.Xr tap 4 , 596.Xr vale 4 , 597.Xr vmnet 4 , 598.Xr bhyve 8 599