xref: /illumos-gate/usr/src/man/man5/bhyve_config.5 (revision badf94ff3599fab15963f6c532929e9bc411757a)
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.\" Portions Copyright 2022 OmniOS Community Edition (OmniOSce) Association.
27.\"
28.Dd April 6, 2022
29.Dt BHYVE_CONFIG 5
30.Os
31.Sh NAME
32.Nm bhyve_config
33.Nd "bhyve configuration variables"
34.Sh DESCRIPTION
35.Xr bhyve 8
36uses a hierarchical tree of configuration variables to describe global and
37per-device settings.
38Internal nodes in this tree do not have a value,
39only leaf nodes have values.
40This manual describes the configuration variables understood by
41.Xr bhyve 8 .
42If additional variables are defined,
43.Xr bhyve 8
44will ignore them and will not emit errors for unknown variables.
45However, these additional variables can be referenced by other
46variables as described below.
47.Sh VARIABLE VALUES
48Configuration variable values are stored as strings.
49A configuration variable value may refer to one or more other
50configuration values by name.
51Instances of the pattern
52.Sq % Ns Pq Ar var
53are replaced by the value of the configuration variable
54.Va var .
55To avoid unwanted expansion,
56.Sq %
57characters can be escaped by a leading
58.Sq % .
59For example,
60if a configuration variable
61.Va disk
62uses the value
63.Pa /dev/zvol/bhyve/%(name) ,
64then the final value of the
65.Va disk
66variable will be set to the path of a ZFS volume whose name matches
67the name of the virtual machine on the pool
68.Pa bhyve .
69.Pp
70Some configuration variables may be interpreted as a boolean value.
71For those variables the following case-insensitive values may be used to
72indicate true:
73.Pp
74.Bl -bullet -offset indent -compact
75.It
76true
77.It
78on
79.It
80yes
81.It
821
83.El
84.Pp
85The following values may be used to indicate false:
86.Pp
87.Bl -bullet -offset indent -compact
88.It
89false
90.It
91off
92.It
93no
94.It
950
96.El
97.Pp
98Some configuration variables may be interpreted as an integer.
99For those variables,
100any syntax supported by
101.Xr strtoul 3C
102may be used.
103.Sh GLOBAL SETTINGS
104.Ss Architecture Neutral Settings
105.Bl -column "memory.guest_in_core" "integer" "Default"
106.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
107.It Va name Ta string Ta Ta
108The name of the VM.
109.It Va cpus Ta integer Ta 1 Ta
110The total number of virtual CPUs.
111.It Va cores Ta integer Ta 1 Ta
112The number of virtual cores in each virtual socket.
113.It Va threads Ta integer Ta 1 Ta
114The number of virtual CPUs in each virtual core.
115.It Va sockets Ta integer Ta 1 Ta
116The number of virtual sockets.
117.It Va memory.size Ta string Ta 256M Ta
118Guest physical memory size.
119The size argument may be suffixed with one of K, M, G or T (either upper
120or lower case) to indicate a multiple of kibibytes, mebibytes, gibibytes,
121or tebibytes.
122If no suffix is given, the value is assumed to be in mebibytes.
123.It Va memory.wired Ta bool Ta false Ta
124Wire guest memory.
125.It Va acpi_tables Ta bool Ta false Ta
126Generate ACPI tables; these tables are
127.Em not
128used on illumos.
129.It Va destroy_on_poweroff Ta bool Ta false Ta
130Destroy the VM on guest-initiated power-off.
131.It Va gdb.address Ta string Ta localhost Ta
132Hostname, IP address, or IPv6 address for the debug server.
133.It Va gdb.port Ta integer Ta 0 Ta
134TCP port number for the debug server.
135If this is set to a non-zero value, a debug server
136will listen for connections on this port.
137.It Va gdb.wait Ta bool Ta false Ta
138If the debug server is enabled, wait for a debugger to connect
139before starting the guest.
140.It Va rtc.use_localtime Ta bool Ta true Ta
141The real time clock uses the local time of the host.
142If this is set to false, the real time clock uses UTC.
143.It Va uuid Ta string Ta Ta
144The universally unique identifier (UUID) to use in the guest's
145System Management BIOS System Information structure.
146If an explicit value is not set, a valid UUID is generated from
147the host's hostname and the VM name.
148.It Va virtio_msix Ta bool Ta true Ta
149Use MSI-X interrupts for PCI VirtIO devices.
150If set to false, MSI interrupts are used instead.
151.It Va config.dump Ta bool Ta false Ta
152If this value is set to true then, after parsing command line options,
153.Xr bhyve 8
154will write all of its configuration variables to
155.Dv stdout
156and exit.
157No VM will be started.
158.It Va privileges.debug Ta bool Ta false Ta
159Enable debug messages relating to privilege management.
160These messages are sent to
161.Dv stdout .
162.It Va rfb.debug Ta bool Ta false Ta
163Enable debug messages relating to the RFB
164.Pq VNC
165server.
166.It Va xhci.debug Ta bool Ta false Ta
167Enable debug messages relating to the emulated XHCI
168.Pq USB
169controller.
170These messages are sent to
171.Dv stderr .
172.El
173.Ss x86-Specific Settings
174.Bl -column "x86.vmexit_on_pause" "integer" "Default"
175.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
176.It Va x86.mptable Ta bool Ta true Ta
177Generate an MPTable.
178.It Va x86.x2apic Ta bool Ta false Ta
179Configure guest's local APICs in x2APIC mode.
180.It Va x86.strictio Ta bool Ta false Ta
181Exit if a guest accesses an I/O port that is not emulated.
182By default, writes are ignored and reads return all bits set.
183.It Va x86.strictmsr Ta bool Ta true Ta
184Inject a general protection fault if a guest accesses a Model Specific
185Register (MSR) that is not emulated.
186If this is false, writes are ignored and reads return zero.
187.It Va x86.vmexit_on_hlt Ta bool Ta false Ta
188Force a VM exit when a guest CPU executes the
189.Dv HLT
190instruction.
191This allows idle guest CPUs to yield the host CPU.
192.It Va x86.vmexit_on_pause Ta bool Ta false Ta
193Force a VM exit when a guest CPU executes the
194.Dv PAUSE
195instruction.
196.El
197.Sh DEVICE SETTINGS
198Device settings are stored under a device node.
199The device node's name is set by the parent bus of the device.
200.Ss PCI Device Settings
201PCI devices are described by a device node named
202.Dq pci . Ns Ar bus . Ns Ar slot . Ns Ar function
203where each of
204.Ar bus ,
205.Ar slot ,
206and
207.Ar function
208are formatted as decimal values with no padding.
209All PCI device nodes must contain a configuration variable named
210.Dq device
211which specifies the device model to use.
212The following PCI device models are supported:
213.Bl -tag -width indent
214.It Li hostbridge
215Provide a simple PCI-Host bridge device.
216This is usually configured at pci0:0:0 and is required by most guest
217operating systems.
218.It Li ahci
219AHCI storage controller.
220.It Li e1000
221Intel e82545 network interface.
222.It Li fbuf
223VGA framebuffer device attached to VNC server.
224.It Li lpc
225LPC PCI-ISA bridge with COM1-COM4 16550 serial ports,
226a boot ROM,
227and an optional debug/test device.
228This device must be configured on bus 0.
229.It Li nvme
230NVM Express (NVMe) controller.
231.It Li passthru
232PCI pass-through device.
233.It Li uart
234PCI 16550 serial device.
235.It Li virtio-9p
236VirtIO 9p (VirtFS) interface.
237.It Li virtio-blk
238VirtIO block storage interface.
239.It Li virtio-console
240VirtIO console interface.
241.It Li virtio-net-viona
242Accelerated VirtIO network interface.
243.It Li net-viona
244Legacy VirtIO network interface.
245.It Li virtio-rnd
246VirtIO random number generator interface.
247.It Li xhci
248Extensible Host Controller Interface (XHCI) USB controller.
249.El
250.Ss USB Device Settings
251USB controller devices contain zero or more child USB devices
252attached to slots.
253Each USB device stores its settings in a node named
254.Dq slot. Ns Va N
255under the controller's device node.
256.Va N
257is the number of the slot to which the USB device is attached.
258Note that USB slot numbers begin at 1.
259All USB device nodes must contain a configuration variable named
260.Dq device
261which specifies the device model to use.
262The following USB device models are supported:
263.Bl -tag -width indent
264.It Li tablet
265A USB tablet device which provides precise cursor synchronization
266when using VNC.
267.El
268.Ss Block Device Settings
269Block devices use the following settings to configure their backing store.
270These settings are stored in the configuration node of the respective device.
271.Bl -column "sectorsize" "logical[/physical]" "Default"
272.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
273.It path Ta string Ta Ta
274The path of the file or disk device to use as the backing store.
275.It nocache Ta bool Ta false Ta
276Disable caching on the backing file by opening the backing file with
277.Dv O_DIRECT .
278.It nodelete Ta bool Ta false Ta
279Disable emulation of guest trim requests via
280.Dv DIOCGDELETE
281requests.
282.It sync Ta bool Ta false Ta
283Write changes to the backing file with synchronous writes.
284.It direct Ta bool Ta false Ta
285An alias for
286.Va sync .
287.It ro Ta bool Ta false Ta
288Disable writes to the backing file.
289.It sectorsize Ta Va logical Ns Op / Ns Va physical Ta Ta
290Specify the logical and physical sector size of the emulated disk.
291If the physical size is not specified, it is set to be equal to the logical
292size.
293.El
294.Ss virtio-net-viona Network Backend Settings
295Viona network devices use the following settings to configure their backend.
296.Bl -column "feature_flags" "string" "Default"
297.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
298.It vnic Ta string Ta Ta
299The VNIC to use for the network connection.
300.It feature_mask Ta integer Ta 0 Ta
301Specify a mask to apply to the virtio features advertised to the guest.
302.El
303.Ss Other Network Backend Settings
304Other network devices use the following settings to configure their backend.
305.Bl -column "feature_flags" "string" "Default"
306.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
307.It vnic Ta string Ta Ta
308The VNIC to use for the network connection.
309.It promiscphys Ta bool Ta false Ta
310Enable promiscuous mode at the physical level.
311.It promiscsap Ta bool Ta true Ta
312Enable promiscuous mode at the SAP level.
313.It promiscmulti Ta bool Ta true Ta
314Enable promiscuous mode for all multicast addresses.
315.It promiscrxonly Ta bool Ta true Ta
316The selected promiscuous modes are only enabled for received traffic.
317.El
318.Ss UART Device Settings
319.Bl -column "Name" "Format" "Default"
320.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
321.It Va path Ta path Ta Ta
322Backend device for the serial port.
323Either the pathname of a character device or
324.Dq stdio
325to use standard input and output of the
326.Xr bhyve 8
327process.
328.El
329.Ss Host Bridge Settings
330Host Bridge devices use the following settings.
331When configuring parameters, either the
332.Va model
333by itself, or both of
334.Va vendor
335and
336.Va devid
337must be specified.
338.Bl -column "vendor" "integer" "Default"
339.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
340.It Va model Ta string Ta netapp Ta
341Specify a hostbridge model to emulate.
342Valid model strings, and their associated vendor and device IDs are:
343.Sy amd Pq 0x1022/0x7432 ,
344.Sy netapp Pq 0x1275/0x1275 ,
345.Sy i440fx Pq 0x8086/0x1237
346and
347.Sy q35 Pq 0x8086/0x29b0 .
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 Frame Buffer Settings
390.Bl -column "password" "[IP:]port" "127.0.0.1:5900"
391.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
392.It Va wait Ta bool Ta false Ta
393Wait for a remote connection before starting the VM.
394.It Va rfb Ta Oo Ar IP Ns \&: Oc Ns Ar port Ta 127.0.0.1:5900 Ta
395TCP address to listen on for remote connections.
396The IP address must be given as a numeric address.
397IPv6 addresses must be enclosed in square brackets and
398support scoped identifiers as described in
399.Xr getaddrinfo 3SOCKET .
400A bare port number may be given in which case the IPv4
401localhost address is used.
402.It Va unix Ta string Ta Ta
403UNIX socket to listen on for VNC connections.
404.It Va vga Ta string Ta io Ta
405VGA configuration.
406More details are provided in
407.Xr bhyve 8 .
408.It Va w Ta integer Ta 1024 Ta
409Frame buffer width in pixels.
410.It Va h Ta integer Ta 768 Ta
411Frame buffer height in pixels.
412.It Va password Ta string Ta Ta
413Password to use for VNC authentication.
414This type of authentication is known to be cryptographically weak and is not
415intended for use on untrusted networks.
416.El
417.Ss LPC Device Settings
418The LPC bridge stores its configuration under a top-level
419.Va lpc
420node rather than under the PCI LPC device's node.
421The following nodes are available under
422.Va lpc :
423.Bl -column "pc-testdev" "Format" "Default"
424.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
425.It Va bootrom Ta path Ta Ta
426Path to a boot ROM.
427The contents of this file are copied into the guest's
428memory ending just before the 4GB physical address.
429If a boot ROM is present, a firmware interface device is
430also enabled for use by the boot ROM.
431.It Va com1 Ta node Ta Ta
432Settings for the COM1 serial port device.
433.It Va com2 Ta node Ta Ta
434Settings for the COM2 serial port device.
435.It Va com3 Ta node Ta Ta
436Settings for the COM3 serial port device.
437.It Va com4 Ta node Ta Ta
438Settings for the COM4 serial port device.
439.It Va pc-testdev Ta bool Ta false Ta
440Enable the PC debug/test device.
441.El
442.Ss NVMe Controller Settings
443Each NVMe controller supports a single storage device.
444The device can be backed either by a memory disk described by the
445.Va ram
446variable, or a block device using the block device settings described above.
447In addition, each controller supports the following settings:
448.Bl -column "ioslots" "Format" "Default"
449.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
450.It Va maxq Ta integer Ta 16 Ta
451Maximum number of I/O submission and completion queue pairs.
452.It Va qsz Ta integer Ta 2058 Ta
453Number of elements in each I/O queue.
454.It Va ioslots Ta integer Ta 8 Ta
455Maximum number of concurrent I/O requests.
456.It Va sectsz Ta integer Ta Ta
457Sector size.
458Can be one of 512, 4096, or 8192.
459Devices backed by a memory disk use 4096 as the default.
460Devices backed by a block device use the block device's sector size
461as the default.
462.It Va ser Ta string Ta Ta
463Serial number of up to twenty characters.
464A default serial number is generated using a hash of the device's PCI address.
465.It Va eui64 Ta integer Ta Ta
466IEEE Extended Unique Identifier.
467If an EUI is not provided, a default is generated using a checksum of the
468device's PCI address.
469.It Va dsm Ta string Ta auto Ta
470Whether or not to advertise Dataset Management (DSM) support.
471One of
472.Dq auto ,
473.Dq enable ,
474or
475.Dq disable .
476The
477.Dq auto
478setting only advertises support if the backing store supports
479resource freeing, for example via TRIM.
480.It Va ram Ta integer Ta Ta
481If set, allocate a memory disk as the backing store.
482The value of this variable is the size of the memory disk in megabytes.
483.El
484.Ss PCI Passthrough Settings
485.Bl -column "Name" "integer" "Default"
486.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
487.It Va path Ta string Ta Ta
488Path to a PCI passthrough device in the form
489.Pa /dev/ppt Ns Ar N
490where
491.Ar N
492is the device number.
493.El
494.Ss VirtIO 9p Settings
495Each VirtIO 9p device exposes a single filesystem from a host path.
496.Bl -column "sharename" "Format" "Default"
497.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
498.It Va sharename Ta string Ta Ta
499The share name exposed to the guest.
500.It Va path Ta path Ta Ta
501The path of a directory on the host to export to the guest.
502.It Va ro Ta bool Ta false Ta
503If true, the guest filesystem is read-only.
504.El
505.Ss VirtIO Block Device Settings
506In addition to the block device settings described above, each
507VirtIO block device supports the following settings:
508.Bl -column "model" "integer" "generated"
509.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
510.It Va ser Ta string Ta generated Ta
511Serial number of up to twenty characters.
512A default serial number is generated using a hash of the backing
513store's pathname.
514.El
515.Ss VirtIO Console Device Settings
516Each VirtIO Console device contains one or more console ports.
517Each port stores its settings in a node named
518.Dq port. Ns Va N
519under the controller's device node.
520The
521.Va N
522values are formatted as successive decimal values starting with 0.
523Each port supports the following settings:
524.Bl -column "Name" "Format" "Default"
525.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
526.It Va name Ta string Ta Ta
527The name of the port exposed to the guest.
528.It Va path Ta path Ta Ta
529The path of a UNIX domain socket providing the host connection for the port.
530.El
531.Sh SEE ALSO
532.Xr strtoul 3C ,
533.Xr getaddrinfo 3SOCKET ,
534.Xr bhyve 8
535