xref: /freebsd/usr.sbin/bhyve/bhyve_config.5 (revision 3332f1b444d4a73238e9f59cca27bfc95fe936bd)
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 September 25, 2021
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 rtc.use_localtime Ta bool Ta true Ta
137The real time clock uses the local time of the host.
138If this is set to false, the real time clock uses UTC.
139.It Va uuid Ta string Ta Ta
140The universally unique identifier (UUID) to use in the guest's
141System Management BIOS System Information structure.
142If an explicit value is not set, a valid UUID is generated from
143the host's hostname and the VM name.
144.It Va virtio_msix Ta bool Ta true Ta
145Use MSI-X interrupts for PCI VirtIO devices.
146If set to false, MSI interrupts are used instead.
147.It Va config.dump Ta bool Ta false Ta
148If this value is set to true after
149.Xr bhyve 8
150has finished parsing command line options,
151then
152.Xr bhyve 8
153will write all of its configuration variables to stdout and exit.
154No VM will be started.
155.El
156.Ss x86-Specific Settings
157.Bl -column "x86.vmexit_on_pause" "integer" "Default"
158.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
159.It Va x86.mptable Ta bool Ta true Ta
160Generate an MPTable.
161.It Va x86.x2apic Ta bool Ta false Ta
162Configure guest's local APICs in x2APIC mode.
163.It Va x86.strictio Ta bool Ta false Ta
164Exit if a guest accesses an I/O port that is not emulated.
165By default, writes are ignored and reads return all bits set.
166.It Va x86.strictmsr Ta bool Ta true Ta
167Inject a general protection fault if a guest accesses a Model Specific
168Register (MSR) that is not emulated.
169If this is false, writes are ignored and reads return zero.
170.It Va x86.vmexit_on_hlt Ta bool Ta false Ta
171Force a VM exit when a guest CPU executes the
172.Dv HLT
173instruction.
174This allows idle guest CPUs to yield the host CPU.
175.It Va x86.vmexit_on_pause Ta bool Ta false Ta
176Force a VM exit when a guest CPU executes the
177.Dv PAUSE
178instruction.
179.El
180.Sh DEVICE SETTINGS
181Device settings are stored under a device node.
182The device node's name is set by the parent bus of the device.
183.Ss PCI Device Settings
184PCI devices are described by a device node named
185.Dq pci . Ns Ar bus . Ns Ar slot . Ns Ar function
186where each of
187.Ar bus ,
188.Ar slot ,
189and
190.Ar function
191are formatted as decimal values with no padding.
192All PCI device nodes must contain a configuration variable named
193.Dq device
194which specifies the device model to use.
195The following PCI device models are supported:
196.Bl -tag -indent
197.It Li hostbridge
198Provide a simple PCI-Host bridge device.
199This is usually configured at pci0:0:0 and is required by most guest
200operating systems.
201.It Li ahci
202AHCI storage controller.
203.It Li e1000
204Intel e82545 network interface.
205.It Li fbuf
206VGA framebuffer device attached to VNC server.
207.It Li lpc
208LPC PCI-ISA bridge with COM1-COM4 16550 serial ports,
209a boot ROM,
210and an optional debug/test device.
211This device must be configured on bus 0.
212.It Li hda
213High Definition audio controller.
214.It Li nvme
215NVM Express (NVMe) controller.
216.It Li passthru
217PCI pass-through device.
218.It Li uart
219PCI 16550 serial device.
220.It Li virtio-9p
221VirtIO 9p (VirtFS) interface.
222.It Li virtio-blk
223VirtIO block storage interface.
224.It Li virtio-console
225VirtIO console interface.
226.It Li virtio-input
227VirtIO input interface.
228.It Li virtio-net
229VirtIO network interface.
230.It Li virtio-rnd
231VirtIO RNG interface.
232.It Li virtio-scsi
233VirtIO SCSI interface.
234.It Li xhci
235Extensible Host Controller Interface (XHCI) USB controller.
236.El
237.Ss USB Device Settings
238USB controller devices contain zero or more child USB devices
239attached to slots.
240Each USB device stores its settings in a node named
241.Dq slot. Ns Va N
242under the controller's device node.
243.Va N
244is the number of the slot to which the USB device is attached.
245Note that USB slot numbers begin at 1.
246All USB device nodes must contain a configuration variable named
247.Dq device
248which specifies the device model to use.
249The following USB device models are supported:
250.Bl -tag -indent
251.It Li tablet
252A USB tablet device which provides precise cursor synchronization
253when using VNC.
254.El
255.Ss Block Device Settings
256Block devices use the following settings to configure their backing store.
257These settings are stored in the configuration node of the respective device.
258.Bl -column "sectorsize" "logical[/physical]" "Default"
259.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
260.It path Ta string Ta Ta
261The path of the file or disk device to use as the backing store.
262.It nocache Ta bool Ta false Ta
263Disable caching on the backing file by opening the backing file with
264.Dv O_DIRECT .
265.It nodelete Ta bool Ta false Ta
266Disable emulation of guest trim requests via
267.Dv DIOCGDELETE
268requests.
269.It sync Ta bool Ta false Ta
270Write changes to the backing file with synchronous writes.
271.It direct Ta bool Ta false Ta
272An alias for
273.Va sync .
274.It ro Ta bool Ta false Ta
275Disable writes to the backing file.
276.It sectorsize Ta Va logical Ns Op / Ns Va physical Ta Ta
277Specify the logical and physical sector size of the emulated disk.
278If the physical size is not specified,
279it is equal to the logical size.
280.El
281.Ss Network Backend Settings
282Network devices use the following settings to configure their backend.
283The backend is responsible for passing packets between the device model
284and a desired destination.
285Configuring a backend requires setting the
286.Va backend
287variable to one of the following values:
288.Bl -tag
289.It tap Ns Va N
290Use the named
291.Xr tap 4
292interface as the backend.
293.It vmnet Ns Va N
294Use the named
295.Xr vmnet 4
296interface as the backend.
297.It netgraph
298Use a
299.Xr netgraph 4
300socket hook as the backend.
301This backend uses the following additional variables:
302.Bl -column "peerhook" "Format" "Default"
303.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
304.It Va path Ta string Ta Ta
305The name of the
306.Xr netgraph 4
307destination node.
308.It Va peerhook Ta string Ta Ta
309The name of the destination hook.
310.It Va socket Ta string Ta Ta
311The name of the created
312.Xr ng_socket 4
313node.
314.It Va hook Ta string Ta vmlink Ta
315The name of the source hook on the created
316.Xr ng_socket 4
317node.
318.El
319.It netmap: Ns Va interface
320Use
321.Xr netmap 4
322on a network interface as the backend.
323.It vale Ns Va bridge : Ns Va port
324Use a port on a
325.Xr vale 4
326bridge as the backend.
327.El
328.Ss UART Device Settings
329.Bl -column "Name" "Format" "Default"
330.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
331.It Va path Ta path Ta Ta
332Backend device for the serial port.
333Either the pathname of a character device or
334.Dq stdio
335to use standard input and output of the
336.Xr bhyve 8
337process.
338.El
339.Ss Host Bridge Settings
340.Bl -column "vendor" "integer" "Default"
341.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
342.It Va vendor Ta integer Ta 0x1275 Ta
343PCI vendor ID.
344.It Va devid Ta integer Ta 0x1275 Ta
345PCI device ID.
346.El
347.Ss AHCI Controller Settings
348AHCI controller devices contain zero or more ports each of which
349provides a storage device.
350Each port stores its settings in a node named
351.Dq port. Ns Va N
352under the controller's device node.
353The
354.Va N
355values are formatted as successive decimal values starting with 0.
356In addition to the block device settings described above, each
357port supports the following settings:
358.Bl -column "model" "integer" "generated"
359.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
360.It Va type Ta string Ta Ta
361The type of storage device to emulate.
362Must be set to either
363.Dq cd
364or
365.Dq hd .
366.It Va nmrr Ta integer Ta 0 Ta
367Nominal Media Rotation Rate, also known as RPM.
368A value 1 of indicates a device with no rate such as a Solid State Disk.
369.It Va ser Ta string Ta generated Ta
370Serial number of up to twenty characters.
371A default serial number is generated using a hash of the backing
372store's pathname.
373.It Va rev Ta string Ta 001 Ta
374Revision number of up to eight characters.
375.It Va model Ta string Ta Ta
376Model number of up to forty characters.
377Separate default model strings are used for
378.Dq cd
379and
380.Dq hd
381device types.
382.El
383.Ss e1000 Settings
384In addition to the network backend settings,
385Intel e82545 network interfaces support the following variables:
386.Bl -column "Name" "MAC address" "generated"
387.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
388.It Va mac Ta MAC address Ta generated Ta
389MAC address.
390If an explicit address is not provided,
391a MAC address is generated from a hash of the device's PCI address.
392.El
393.Ss Frame Buffer Settings
394.Bl -column "password" "[IP:]port" "127.0.0.1:5900"
395.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
396.It Va wait Ta bool Ta false Ta
397Wait for a remote connection before starting the VM.
398.It Va rfb Ta Oo Ar IP Ns : Oc Ns Ar port Ta 127.0.0.1:5900 Ta
399TCP address to listen on for remote connections.
400The IP address must be given as a numeric address.
401IPv6 addresses must be enclosed in square brackets and
402support scoped identifiers as described in
403.Xr getaddrinfo 3 .
404A bare port number may be given in which case the IPv4
405localhost address is used.
406.It Va vga Ta string Ta io Ta
407VGA configuration.
408More details are provided in
409.Xr bhyve 8 .
410.It Va w Ta integer Ta 1024 Ta
411Frame buffer width in pixels.
412.It Va h Ta integer Ta 768 Ta
413Frame buffer height in pixels.
414.It Va password Ta string Ta Ta
415Password to use for VNC authentication.
416This type of authentication is known to be cryptographically weak and is not
417intended for use on untrusted networks.
418.El
419.Ss High Definition Audio Settings
420.Bl -column "Name" "Format" "Default"
421.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
422.It Va play Ta path Ta Ta
423Host playback device,
424typically
425.Pa /dev/dsp0 .
426.It Va rec Ta path Ta Ta
427Host recording device,
428typically
429.Pa /dev/dsp0 .
430.El
431.Ss LPC Device Settings
432The LPC bridge stores its configuration under a top-level
433.Va lpc
434node rather than under the PCI LPC device's node.
435The following nodes are available under
436.Va lpc :
437.Bl -column "pc-testdev" "Format" "Default"
438.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
439.It Va bootrom Ta path Ta Ta
440Path to a boot ROM.
441The contents of this file are copied into the guest's
442memory ending just before the 4GB physical address.
443If a boot ROM is present, a firmware interface device is
444also enabled for use by the boot ROM.
445.It Va com1 Ta node Ta Ta
446Settings for the COM1 serial port device.
447.It Va com2 Ta node Ta Ta
448Settings for the COM2 serial port device.
449.It Va com3 Ta node Ta Ta
450Settings for the COM3 serial port device.
451.It Va com4 Ta node Ta Ta
452Settings for the COM4 serial port device.
453.It Va pc-testdev Ta bool Ta false Ta
454Enable the PC debug/test device.
455.El
456.Ss NVMe Controller Settings
457Each NVMe controller supports a single storage device.
458The device can be backed either by a memory disk described by the
459.Va ram
460variable, or a block device using the the block device settings described above.
461In addition, each controller supports the following settings:
462.Bl -column "ioslots" "Format" "Default"
463.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
464.It Va maxq Ta integer Ta 16 Ta
465Maximum number of I/O submission and completion queue pairs.
466.It Va qsz Ta integer Ta 2058 Ta
467Number of elements in each I/O queue.
468.It Va ioslots Ta integer Ta 8 Ta
469Maximum number of concurrent I/O requests.
470.It Va sectsz Ta integer Ta Ta
471Sector size.
472Can be one of 512, 4096, or 8192.
473Devices backed by a memory disk use 4096 as the default.
474Devices backed by a block device use the block device's sector size
475as the default.
476.It Va ser Ta string Ta Ta
477Serial number of up to twenty characters.
478A default serial number is generated using a hash of the device's PCI address.
479.It Va eui64 Ta integer Ta Ta
480IEEE Extended Unique Identifier.
481If an EUI is not provided, a default is generated using a checksum of the
482device's PCI address.
483.It Va dsm Ta string Ta auto Ta
484Whether or not to advertise DataSet Management support.
485One of
486.Dq auto ,
487.Dq enable ,
488or
489.Dq disable .
490The
491.Dq auto
492setting only advertises support if the backing store supports
493resource freeing, for example via TRIM.
494.It Va ram Ta integer Ta Ta
495If set, allocate a memory disk as the backing store.
496The value of this variable is the size of the memory disk in megabytes.
497.El
498.Ss PCI Passthrough Settings
499.Bl -column "Name" "integer" "Default"
500.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
501.It Va bus Ta integer Ta Ta
502Host PCI bus address of device to pass through.
503.It Va slot Ta integer Ta Ta
504Host PCI slot address of device to pass through.
505.It Va func Ta integer Ta Ta
506Host PCI function address of device to pass through.
507.El
508.Ss VirtIO 9p Settings
509Each VirtIO 9p device exposes a single filesystem from a host path.
510.Bl -column "sharename" "Format" "Default"
511.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
512.It Va sharename Ta string Ta Ta
513The share name exposed to the guest.
514.It Va path Ta path Ta Ta
515The path of a directory on the host to export to the guest.
516.It Va ro Ta bool Ta false Ta
517If true, the guest filesystem is read-only.
518.El
519.Ss VirtIO Block Device Settings
520In addition to the block device settings described above, each
521VirtIO block device supports the following settings:
522.Bl -column "model" "integer" "generated"
523.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
524.It Va ser Ta string Ta generated Ta
525Serial number of up to twenty characters.
526A default serial number is generated using a hash of the backing
527store's pathname.
528.El
529.Ss VirtIO Console Device Settings
530Each VirtIO Console device contains one or more console ports.
531Each port stores its settings in a node named
532.Dq port. Ns Va N
533under the controller's device node.
534The
535.Va N
536values are formatted as successive decimal values starting with 0.
537Each port supports the following settings:
538.Bl -column "Name" "Format" "Default"
539.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
540.It Va name Ta string Ta Ta
541The name of the port exposed to the guest.
542.It Va path Ta path Ta Ta
543The path of a UNIX domain socket providing the host connection for the port.
544.El
545.Ss VirtIO Input Interface Settings
546Each VirtIO Input device contains one input event device.
547All input events of the input event device are send to the guest by VirtIO Input interface.
548VirtIO Input Interfaces support the following variables:
549.Bl -column "Name" "Format" "Default"
550.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
551.It Va path Ta path Ta Ta
552The path of the input event device exposed to the guest
553.El
554.Ss VirtIO Network Interface Settings
555In addition to the network backend settings,
556VirtIO network interfaces support the following variables:
557.Bl -column "Name" "MAC address" "generated"
558.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
559.It Va mac Ta MAC address Ta generated Ta
560MAC address.
561If an explicit address is not provided,
562a MAC address is generated from a hash of the device's PCI address.
563.It Va mtu Ta integer Ta 1500 Ta
564The largest supported MTU advertised to the guest.
565.El
566.Ss VirtIO SCSI Settings
567.Bl -column "Name" "integer" "Default"
568.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description
569.It Va dev Ta path Ta Ta
570The path of a CAM target layer (CTL) device to export:
571.Pa /dev/cam/ctl Ns Oo Ar pp . Ns Ar vp Oc .
572.It Va iid Ta integer Ta 0 Ta
573Initiator ID to use when sending requests to the CTL port.
574.El
575.Sh SEE ALSO
576.Xr expand_number 3 ,
577.Xr getaddrinfo 3 ,
578.Xr strtol 3 ,
579.Xr netgraph 4 ,
580.Xr netmap 4 ,
581.Xr ng_socket 4 ,
582.Xr tap 4 ,
583.Xr vale 4 ,
584.Xr vmnet 4 ,
585.Xr bhyve 8
586