1 .\" SPDX-License-Identifier: BSD-2-Clause
3 .\" Copyright (c) 2021 John H. Baldwin <jhb@FreeBSD.org>
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
31 .Nd "bhyve configuration variables"
34 uses a hierarchical tree of configuration variables to describe global and
36 Internal nodes in this tree do not have a value,
37 only leaf nodes have values.
38 This manual describes the configuration variables understood by
40 If additional variables are defined,
42 will ignore them and will not emit errors for unknown variables.
43 However, these additional variables can be referenced by other
44 variables as described below.
46 Configuration variable values are stored as strings.
47 A configuration variable value may refer to one or more other
48 configuration values by name.
49 Instances of the pattern
51 are replaced by the value of the configuration variable
53 To avoid unwanted expansion,
55 characters can be escaped by a leading
58 if a configuration variable
61 .Pa /dev/zvol/bhyve/%(name) ,
62 then the final value of the
64 variable will be set to the path of a ZFS volume whose name matches
65 the name of the virtual machine on the pool
68 Some configuration variables may be interpreted as a boolean value.
69 For those variables the following case-insensitive values may be used to
72 .Bl -bullet -offset indent -compact
83 The following values may be used to indicate false:
85 .Bl -bullet -offset indent -compact
96 Some configuration variables may be interperted as an integer.
98 any syntax supported by
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
107 .It Va cpus Ta integer Ta 1 Ta
108 The total number of virtual CPUs.
109 .It Va cores Ta integer Ta 1 Ta
110 The number of virtual cores in each virtual socket.
111 .It Va threads Ta integer Ta 1 Ta
112 The number of virtual CPUs in each virtual core.
113 .It Va sockets Ta integer Ta 1 Ta
114 The number of virtual sockets.
115 .It Va memory.guest_in_core Ta bool Ta false Ta
116 Include guest memory in core file.
117 .It Va memory.size Ta string Ta 256M Ta
118 Guest physical memory size in bytes.
119 The value must be formatted as described in
120 .Xr expand_number 3 .
121 .It Va memory.wired Ta bool Ta false Ta
123 .It Va acpi_tables Ta bool Ta false Ta
124 Generate ACPI tables.
125 .It Va destroy_on_poweroff Ta bool Ta false Ta
126 Destroy the VM on guest-initiated power-off.
127 .It Va gdb.address Ta string Ta localhost Ta
128 Hostname, IP address, or IPv6 address for the debug server.
129 .It Va gdb.port Ta integer Ta 0 Ta
130 TCP port number for the debug server.
131 If this is set to a non-zero value, a debug server
132 will listen for connections on this port.
133 .It Va gdb.wait Ta bool Ta false Ta
134 If the debug server is enabled, wait for a debugger to connect
135 before starting the guest.
136 .It Va rtc.use_localtime Ta bool Ta true Ta
137 The real time clock uses the local time of the host.
138 If this is set to false, the real time clock uses UTC.
139 .It Va uuid Ta string Ta Ta
140 The universally unique identifier (UUID) to use in the guest's
141 System Management BIOS System Information structure.
142 If an explicit value is not set, a valid UUID is generated from
143 the host's hostname and the VM name.
144 .It Va virtio_msix Ta bool Ta true Ta
145 Use MSI-X interrupts for PCI VirtIO devices.
146 If set to false, MSI interrupts are used instead.
147 .It Va config.dump Ta bool Ta false Ta
148 If this value is set to true after
150 has finished parsing command line options,
153 will write all of its configuration variables to stdout and exit.
154 No VM will be started.
155 .It Va bios.vendor Ta string Ta BHYVE Ta
156 This value is used for the guest's System Management BIOS System Information structure.
157 .It Va bios.version Ta string Ta 14.0 Ta
158 This value is used for the guest's System Management BIOS System Information structure.
159 .It Va bios.release_date Ta string Ta 10/17/2021 Ta
160 This value is used for the guest's System Management BIOS System Information structure.
161 .It Va system.family_name Ta string Ta Virtual Machine Ta
162 Family the computer belongs to.
163 This value is used for the guest's System Management BIOS System Information structure.
164 .It Va system.manufacturer Ta string Ta FreeBSD Ta
165 This value is used for the guest's System Management BIOS System Information structure.
166 .It Va system.product_name Ta string Ta BHYVE Ta
167 This value is used for the guest's System Management BIOS System Information structure.
168 .It Va system.serial_number Ta string Ta None Ta
169 This value is used for the guest's System Management BIOS System Information structure.
170 .It Va system.sku Ta string Ta None Ta
171 Stock keeping unit of the computer.
172 It's also called product ID or purchase order number.
173 This value is used for the guest's System Management BIOS System Information structure.
174 .It Va system.version Ta string Ta 1.0 Ta
175 This value is used for the guest's System Management BIOS System Information structure.
176 .It Va board.manufacturer Ta string Ta FreeBSD Ta
177 This value is used for the guest's System Management BIOS System Information structure.
178 .It Va board.product_name Ta string Ta BHYVE Ta
179 This value is used for the guest's System Management BIOS System Information structure.
180 .It Va board.version Ta string Ta 1.0 Ta
181 This value is used for the guest's System Management BIOS System Information structure.
182 .It Va board.serial_number Ta string Ta None Ta
183 This value is used for the guest's System Management BIOS System Information structure.
184 .It Va board.asset_tag Ta string Ta None Ta
185 This value is used for the guest's System Management BIOS System Information structure.
186 .It Va board.location Ta string Ta None Ta
187 Describes the board's location within the chassis.
188 This value is used for the guest's System Management BIOS System Information structure.
189 .It Va chassis.manufacturer Ta string Ta FreeBSD Ta
190 This value is used for the guest's System Management BIOS System Information structure.
191 .It Va chassis.version Ta string Ta 1.0 Ta
192 This value is used for the guest's System Management BIOS System Information structure.
193 .It Va chassis.serial_number Ta string Ta None Ta
194 This value is used for the guest's System Management BIOS System Information structure.
195 .It Va chassis.asset_tag Ta string Ta None Ta
196 This value is used for the guest's System Management BIOS System Information structure.
197 .It Va chassis.sku Ta string Ta None Ta
198 Stock keeping unit of the chassis.
199 It's also called product ID or purchase order number.
200 This value is used for the guest's System Management BIOS System Information structure.
202 .Ss x86-Specific Settings
203 .Bl -column "x86.vmexit_on_pause" "integer" "Default"
204 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
205 .It Va x86.mptable Ta bool Ta true Ta
207 .It Va x86.x2apic Ta bool Ta false Ta
208 Configure guest's local APICs in x2APIC mode.
209 .It Va x86.strictio Ta bool Ta false Ta
210 Exit if a guest accesses an I/O port that is not emulated.
211 By default, writes are ignored and reads return all bits set.
212 .It Va x86.strictmsr Ta bool Ta true Ta
213 Inject a general protection fault if a guest accesses a Model Specific
214 Register (MSR) that is not emulated.
215 If this is false, writes are ignored and reads return zero.
216 .It Va x86.vmexit_on_hlt Ta bool Ta false Ta
217 Force a VM exit when a guest CPU executes the
220 This allows idle guest CPUs to yield the host CPU.
221 .It Va x86.vmexit_on_pause Ta bool Ta false Ta
222 Force a VM exit when a guest CPU executes the
227 Device settings are stored under a device node.
228 The device node's name is set by the parent bus of the device.
229 .Ss PCI Device Settings
230 PCI devices are described by a device node named
231 .Dq pci Ns Ar bus . Ns Ar slot . Ns Ar function
237 are formatted as decimal values with no padding.
238 All PCI device nodes must contain a configuration variable named
240 which specifies the device model to use.
241 The following PCI device models are supported:
244 Provide a simple PCI-Host bridge device.
245 This is usually configured at pci0:0:0 and is required by most guest
248 AHCI storage controller.
250 Intel e82545 network interface.
252 VGA framebuffer device attached to VNC server.
254 LPC PCI-ISA bridge with COM1-COM4 16550 serial ports,
256 and an optional debug/test device.
257 This device must be configured on bus 0.
259 High Definition audio controller.
261 NVM Express (NVMe) controller.
263 PCI pass-through device.
265 PCI 16550 serial device.
267 VirtIO 9p (VirtFS) interface.
269 VirtIO block storage interface.
270 .It Li virtio-console
271 VirtIO console interface.
273 VirtIO network interface.
275 VirtIO RNG interface.
277 VirtIO SCSI interface.
279 Extensible Host Controller Interface (XHCI) USB controller.
281 .Ss USB Device Settings
282 USB controller devices contain zero or more child USB devices
284 Each USB device stores its settings in a node named
286 under the controller's device node.
288 is the number of the slot to which the USB device is attached.
289 Note that USB slot numbers begin at 1.
290 All USB device nodes must contain a configuration variable named
292 which specifies the device model to use.
293 The following USB device models are supported:
296 A USB tablet device which provides precise cursor synchronization
299 .Ss Block Device Settings
300 Block devices use the following settings to configure their backing store.
301 These settings are stored in the configuration node of the respective device.
302 .Bl -column "sectorsize" "logical[/physical]" "Default"
303 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
304 .It path Ta string Ta Ta
305 The path of the file or disk device to use as the backing store.
306 .It nocache Ta bool Ta false Ta
307 Disable caching on the backing file by opening the backing file with
309 .It nodelete Ta bool Ta false Ta
310 Disable emulation of guest trim requests via
313 .It sync Ta bool Ta false Ta
314 Write changes to the backing file with synchronous writes.
315 .It direct Ta bool Ta false Ta
318 .It ro Ta bool Ta false Ta
319 Disable writes to the backing file.
320 .It sectorsize Ta Va logical Ns Op / Ns Va physical Ta Ta
321 Specify the logical and physical sector size of the emulated disk.
322 If the physical size is not specified,
323 it is equal to the logical size.
325 .Ss Network Backend Settings
326 Network devices use the following settings to configure their backend.
327 The backend is responsible for passing packets between the device model
328 and a desired destination.
329 Configuring a backend requires setting the
332 The type of a backend can either be set explicitly via the
335 or it can be inferred from the value of
338 The following types of backends are supported:
339 .Bl -tag -width "netgraph"
349 socket hook as the backend.
350 This backend uses the following additional variables:
351 .Bl -column "peerhook" "Format" "Default"
352 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
353 .It Va path Ta string Ta Ta
357 .It Va peerhook Ta string Ta Ta
358 The name of the destination hook.
359 .It Va socket Ta string Ta Ta
360 The name of the created
363 .It Va hook Ta string Ta vmlink Ta
364 The name of the source hook on the created
371 either on a network interface or a port on a
373 bridge as the backend.
378 to connect to a netmap port.
383 is not specified explicitly, then it is inferred from
385 based on the following patterns:
386 .Bl -column -offset indent "valuebridge:port"
387 .It Sy Pattern Ta Sy Type
388 .It tap Ns Va N Ta tap
389 .It vmnet Ns Va N Ta tap
390 .It netgraph Ta netgraph
391 .It netmap: Ns Va interface Ta netmap
392 .It vale Ns Va bridge : Ns Va port Ta netmap
394 .Ss UART Device Settings
395 .Bl -column "Name" "Format" "Default"
396 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
397 .It Va path Ta path Ta Ta
398 Backend device for the serial port.
399 Either the pathname of a character device or
401 to use standard input and output of the
405 .Ss Host Bridge Settings
406 .Bl -column "vendor" "integer" "Default"
407 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
408 .It Va vendor Ta integer Ta 0x1275 Ta
410 .It Va devid Ta integer Ta 0x1275 Ta
413 .Ss AHCI Controller Settings
414 AHCI controller devices contain zero or more ports each of which
415 provides a storage device.
416 Each port stores its settings in a node named
418 under the controller's device node.
421 values are formatted as successive decimal values starting with 0.
422 In addition to the block device settings described above, each
423 port supports the following settings:
424 .Bl -column "model" "integer" "generated"
425 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
426 .It Va type Ta string Ta Ta
427 The type of storage device to emulate.
428 Must be set to either
432 .It Va nmrr Ta integer Ta 0 Ta
433 Nominal Media Rotation Rate, also known as RPM.
434 A value 1 of indicates a device with no rate such as a Solid State Disk.
435 .It Va ser Ta string Ta generated Ta
436 Serial number of up to twenty characters.
437 A default serial number is generated using a hash of the backing
439 .It Va rev Ta string Ta 001 Ta
440 Revision number of up to eight characters.
441 .It Va model Ta string Ta Ta
442 Model number of up to forty characters.
443 Separate default model strings are used for
450 In addition to the network backend settings,
451 Intel e82545 network interfaces support the following variables:
452 .Bl -column "Name" "MAC address" "generated"
453 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
454 .It Va mac Ta MAC address Ta generated Ta
456 If an explicit address is not provided,
457 a MAC address is generated from a hash of the device's PCI address.
459 .Ss Frame Buffer Settings
460 .Bl -column "password" "[IP:]port" "127.0.0.1:5900"
461 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
462 .It Va wait Ta bool Ta false Ta
463 Wait for a remote connection before starting the VM.
464 .It Va rfb Ta Oo Ar IP Ns : Oc Ns Ar port Ta 127.0.0.1:5900 Ta
465 TCP address to listen on for remote connections.
466 The IP address must be given as a numeric address.
467 IPv6 addresses must be enclosed in square brackets and
468 support scoped identifiers as described in
470 A bare port number may be given in which case the IPv4
471 localhost address is used.
472 .It Va vga Ta string Ta io Ta
474 More details are provided in
476 .It Va w Ta integer Ta 1024 Ta
477 Frame buffer width in pixels.
478 .It Va h Ta integer Ta 768 Ta
479 Frame buffer height in pixels.
480 .It Va password Ta string Ta Ta
481 Password to use for VNC authentication.
482 This type of authentication is known to be cryptographically weak and is not
483 intended for use on untrusted networks.
485 .Ss High Definition Audio Settings
486 .Bl -column "Name" "Format" "Default"
487 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
488 .It Va play Ta path Ta Ta
489 Host playback device,
492 .It Va rec Ta path Ta Ta
493 Host recording device,
497 .Ss LPC Device Settings
498 The LPC bridge stores its configuration under a top-level
500 node rather than under the PCI LPC device's node.
501 The following nodes are available under
503 .Bl -column "pc-testdev" "Format" "Default"
504 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
505 .It Va bootrom Ta path Ta Ta
507 The contents of this file are copied into the guest's
508 memory ending just before the 4GB physical address.
509 If a boot ROM is present, a firmware interface device is
510 also enabled for use by the boot ROM.
511 .It Va com1 Ta node Ta Ta
512 Settings for the COM1 serial port device.
513 .It Va com2 Ta node Ta Ta
514 Settings for the COM2 serial port device.
515 .It Va com3 Ta node Ta Ta
516 Settings for the COM3 serial port device.
517 .It Va com4 Ta node Ta Ta
518 Settings for the COM4 serial port device.
519 .It Va pc-testdev Ta bool Ta false Ta
520 Enable the PC debug/test device.
522 .Ss NVMe Controller Settings
523 Each NVMe controller supports a single storage device.
524 The device can be backed either by a memory disk described by the
526 variable, or a block device using the the block device settings described above.
527 In addition, each controller supports the following settings:
528 .Bl -column "ioslots" "Format" "Default"
529 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
530 .It Va maxq Ta integer Ta 16 Ta
531 Maximum number of I/O submission and completion queue pairs.
532 .It Va qsz Ta integer Ta 2058 Ta
533 Number of elements in each I/O queue.
534 .It Va ioslots Ta integer Ta 8 Ta
535 Maximum number of concurrent I/O requests.
536 .It Va sectsz Ta integer Ta Ta
538 Can be one of 512, 4096, or 8192.
539 Devices backed by a memory disk use 4096 as the default.
540 Devices backed by a block device use the block device's sector size
542 .It Va ser Ta string Ta Ta
543 Serial number of up to twenty characters.
544 A default serial number is generated using a hash of the device's PCI address.
545 .It Va eui64 Ta integer Ta Ta
546 IEEE Extended Unique Identifier.
547 If an EUI is not provided, a default is generated using a checksum of the
548 device's PCI address.
549 .It Va dsm Ta string Ta auto Ta
550 Whether or not to advertise DataSet Management support.
558 setting only advertises support if the backing store supports
559 resource freeing, for example via TRIM.
560 .It Va ram Ta integer Ta Ta
561 If set, allocate a memory disk as the backing store.
562 The value of this variable is the size of the memory disk in megabytes.
564 .Ss PCI Passthrough Settings
567 device driver must be attached to the
568 PCI device being passed through.
569 The device to pass through can be identified either by name or its
570 host PCI bus location.
571 .Bl -column "Name" "integer" "Default"
572 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
573 .It Va bus Ta integer Ta Ta
574 Host PCI bus address of device to pass through.
575 .It Va slot Ta integer Ta Ta
576 Host PCI slot address of device to pass through.
577 .It Va func Ta integer Ta Ta
578 Host PCI function address of device to pass through.
579 .It Va pptdev Ta string Ta Ta
582 device to pass through.
583 .It Va rom Ta path Ta Ta
584 ROM file of the device which will be executed by OVMF to init the device.
586 .Ss VirtIO 9p Settings
587 Each VirtIO 9p device exposes a single filesystem from a host path.
588 .Bl -column "sharename" "Format" "Default"
589 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
590 .It Va sharename Ta string Ta Ta
591 The share name exposed to the guest.
592 .It Va path Ta path Ta Ta
593 The path of a directory on the host to export to the guest.
594 .It Va ro Ta bool Ta false Ta
595 If true, the guest filesystem is read-only.
597 .Ss VirtIO Block Device Settings
598 In addition to the block device settings described above, each
599 VirtIO block device supports the following settings:
600 .Bl -column "model" "integer" "generated"
601 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
602 .It Va ser Ta string Ta generated Ta
603 Serial number of up to twenty characters.
604 A default serial number is generated using a hash of the backing
607 .Ss VirtIO Console Device Settings
608 Each VirtIO Console device contains one or more console ports.
609 Each port stores its settings in a node named
611 under the controller's device node.
614 values are formatted as successive decimal values starting with 0.
615 Each port supports the following settings:
616 .Bl -column "Name" "Format" "Default"
617 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
618 .It Va name Ta string Ta Ta
619 The name of the port exposed to the guest.
620 .It Va path Ta path Ta Ta
621 The path of a UNIX domain socket providing the host connection for the port.
623 .Ss VirtIO Network Interface Settings
624 In addition to the network backend settings,
625 VirtIO network interfaces support the following variables:
626 .Bl -column "Name" "MAC address" "generated"
627 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
628 .It Va mac Ta MAC address Ta generated Ta
630 If an explicit address is not provided,
631 a MAC address is generated from a hash of the device's PCI address.
632 .It Va mtu Ta integer Ta 1500 Ta
633 The largest supported MTU advertised to the guest.
635 .Ss VirtIO SCSI Settings
636 .Bl -column "Name" "integer" "Default"
637 .It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
638 .It Va dev Ta path Ta Ta
639 The path of a CAM target layer (CTL) device to export:
640 .Pa /dev/cam/ctl Ns Oo Ar pp . Ns Ar vp Oc .
641 .It Va iid Ta integer Ta 0 Ta
642 Initiator ID to use when sending requests to the CTL port.
645 .Xr expand_number 3 ,