diff options
Diffstat (limited to 'usr/src/man/man4/bhyve_config.4')
| -rw-r--r-- | usr/src/man/man4/bhyve_config.4 | 524 |
1 files changed, 0 insertions, 524 deletions
diff --git a/usr/src/man/man4/bhyve_config.4 b/usr/src/man/man4/bhyve_config.4 deleted file mode 100644 index 94572b7ace..0000000000 --- a/usr/src/man/man4/bhyve_config.4 +++ /dev/null @@ -1,524 +0,0 @@ -.\" SPDX-License-Identifier: BSD-2-Clause -.\" -.\" Copyright (c) 2021 John H. Baldwin <jhb@FreeBSD.org> -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" Portions Copyright 2022 OmniOS Community Edition (OmniOSce) Association. -.\" -.Dd February 26, 2022 -.Dt BHYVE_CONFIG 4 -.Os -.Sh NAME -.Nm bhyve_config -.Nd "bhyve configuration variables" -.Sh DESCRIPTION -.Xr bhyve 1M -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 configuration variables understood by -.Xr bhyve 1M . -If additional variables are defined, -.Xr bhyve 1M -will ignore them and will not emit errors for unknown variables. -However, these additional variables can be referenced by other -variables as described below. -.Sh VARIABLE VALUES -Configuration variable values are stored as strings. -A configuration variable value may refer to one or more other -configuration values by name. -Instances of the pattern -.Sq % Ns Pq Ar var -are replaced by the value of the configuration variable -.Va var . -To avoid unwanted expansion, -.Sq % -characters can be escaped by a leading -.Sq % . -For example, -if a configuration variable -.Va disk -uses the value -.Pa /dev/zvol/bhyve/%(name) , -then the final value of the -.Va disk -variable will be set to the path of a ZFS volume whose name matches -the name of the virtual machine on the pool -.Pa bhyve . -.Pp -Some configuration variables may be interpreted as a boolean value. -For those variables the following case-insensitive values may be used to -indicate true: -.Pp -.Bl -bullet -offset indent -compact -.It -true -.It -on -.It -yes -.It -1 -.El -.Pp -The following values may be used to indicate false: -.Pp -.Bl -bullet -offset indent -compact -.It -false -.It -off -.It -no -.It -0 -.El -.Pp -Some configuration variables may be interpreted as an integer. -For those variables, -any syntax supported by -.Xr strtoul 3C -may be used. -.Sh GLOBAL SETTINGS -.Ss Architecture Neutral Settings -.Bl -column "memory.guest_in_core" "integer" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va name Ta string Ta Ta -The name of the VM. -.It Va cpus Ta integer Ta 1 Ta -The total number of virtual CPUs. -.It Va cores Ta integer Ta 1 Ta -The number of virtual cores in each virtual socket. -.It Va threads Ta integer Ta 1 Ta -The number of virtual CPUs in each virtual core. -.It Va sockets Ta integer Ta 1 Ta -The number of virtual sockets. -.It Va memory.size Ta string Ta 256M Ta -Guest physical memory size. -The size argument may be suffixed with one of K, M, G or T (either upper -or lower case) to indicate a multiple of kibibytes, mebibytes, gibibytes, -or tebibytes. -If no suffix is given, the value is assumed to be in mebibytes. -.It Va memory.wired Ta bool Ta false Ta -Wire guest memory. -.It Va acpi_tables Ta bool Ta false Ta -Generate ACPI tables; these tables are -.Em not -used on illumos. -.It Va destroy_on_poweroff Ta bool Ta false Ta -Destroy the VM on guest-initiated power-off. -.It Va gdb.address Ta string Ta localhost Ta -Hostname, IP address, or IPv6 address for the debug server. -.It Va gdb.port Ta integer Ta 0 Ta -TCP port number for the debug server. -If this is set to a non-zero value, a debug server -will listen for connections on this port. -.It Va gdb.wait Ta bool Ta false Ta -If the debug server is enabled, wait for a debugger to connect -before starting the guest. -.It Va rtc.use_localtime Ta bool Ta true Ta -The real time clock uses the local time of the host. -If this is set to false, the real time clock uses UTC. -.It Va uuid Ta string Ta Ta -The universally unique identifier (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. -.It Va virtio_msix Ta bool Ta true Ta -Use MSI-X interrupts for PCI VirtIO devices. -If set to false, MSI interrupts are used instead. -.It Va config.dump Ta bool Ta false Ta -If this value is set to true then, after parsing command line options, -.Xr bhyve 1M -will write all of its configuration variables to -.Dv stdout -and exit. -No VM will be started. -.It Va privileges.debug Ta bool Ta false Ta -Enable debug messages relating to privilege management. -These messages are sent to -.Dv stdout . -.El -.Ss x86-Specific Settings -.Bl -column "x86.vmexit_on_pause" "integer" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va x86.mptable Ta bool Ta true Ta -Generate an MPTable. -.It Va x86.x2apic Ta bool Ta false Ta -Configure guest's local APICs in x2APIC mode. -.It Va x86.strictio Ta bool Ta false Ta -Exit if a guest accesses an I/O port that is not emulated. -By default, writes are ignored and reads return all bits set. -.It Va x86.strictmsr Ta bool Ta true Ta -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. -.It Va x86.vmexit_on_hlt Ta bool Ta false Ta -Force a VM exit when a guest CPU executes the -.Dv HLT -instruction. -This allows idle guest CPUs to yield the host CPU. -.It Va x86.vmexit_on_pause Ta bool Ta false Ta -Force a VM exit when a guest CPU executes the -.Dv PAUSE -instruction. -.El -.Sh DEVICE SETTINGS -Device settings are stored under a device node. -The device node's name is set by the parent bus of the device. -.Ss PCI Device Settings -PCI devices are described by a device node named -.Dq pci . Ns Ar bus . Ns Ar slot . Ns Ar function -where each of -.Ar bus , -.Ar slot , -and -.Ar function -are formatted as decimal values with no padding. -All PCI device nodes must contain a configuration variable named -.Dq device -which specifies the device model to use. -The following PCI device models are supported: -.Bl -tag -width indent -.It Li hostbridge -Provide a simple PCI-Host bridge device. -This is usually configured at pci0:0:0 and is required by most guest -operating systems. -.It Li ahci -AHCI storage controller. -.It Li e1000 -Intel e82545 network interface. -.It Li fbuf -VGA framebuffer device attached to VNC server. -.It Li lpc -LPC PCI-ISA bridge with COM1-COM4 16550 serial ports, -a boot ROM, -and an optional debug/test device. -This device must be configured on bus 0. -.It Li nvme -NVM Express (NVMe) controller. -.It Li passthru -PCI pass-through device. -.It Li uart -PCI 16550 serial device. -.It Li virtio-9p -VirtIO 9p (VirtFS) interface. -.It Li virtio-blk -VirtIO block storage interface. -.It Li virtio-console -VirtIO console interface. -.It Li virtio-net-viona -Accelerated VirtIO network interface. -.It Li net-viona -Legacy VirtIO network interface. -.It Li virtio-rnd -VirtIO random number generator interface. -.It Li xhci -Extensible Host Controller Interface (XHCI) USB controller. -.El -.Ss 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 -.Dq slot. Ns Va N -under the controller's device node. -.Va 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 -.Dq device -which specifies the device model to use. -The following USB device models are supported: -.Bl -tag -width indent -.It Li tablet -A USB tablet device which provides precise cursor synchronization -when using VNC. -.El -.Ss 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 device. -.Bl -column "sectorsize" "logical[/physical]" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It path Ta string Ta Ta -The path of the file or disk device to use as the backing store. -.It nocache Ta bool Ta false Ta -Disable caching on the backing file by opening the backing file with -.Dv O_DIRECT . -.It nodelete Ta bool Ta false Ta -Disable emulation of guest trim requests via -.Dv DIOCGDELETE -requests. -.It sync Ta bool Ta false Ta -Write changes to the backing file with synchronous writes. -.It direct Ta bool Ta false Ta -An alias for -.Va sync . -.It ro Ta bool Ta false Ta -Disable writes to the backing file. -.It sectorsize Ta Va logical Ns Op / Ns Va physical Ta Ta -Specify the logical and physical sector size of the emulated disk. -If the physical size is not specified, it is set to be equal to the logical -size. -.El -.Ss virtio-net-viona Network Backend Settings -Viona network devices use the following settings to configure their backend. -.Bl -column "feature_flags" "string" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It vnic Ta string Ta Ta -The VNIC to use for the network connection. -.It feature_mask Ta integer Ta 0 Ta -Specify a mask to apply to the virtio features advertised to the guest. -.El -.Ss Other Network Backend Settings -Other network devices use the following settings to configure their backend. -.Bl -column "feature_flags" "string" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It vnic Ta string Ta Ta -The VNIC to use for the network connection. -.It promiscphys Ta bool Ta false Ta -Enable promiscuous mode at the physical level. -.It promiscsap Ta bool Ta true Ta -Enable promiscuous mode at the SAP level. -.It promiscmulti Ta bool Ta true Ta -Enable promiscuous mode for all multicast addresses. -.It promiscrxonly Ta bool Ta true Ta -The selected promiscuous modes are only enabled for received traffic. -.El -.Ss UART Device Settings -.Bl -column "Name" "Format" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va path Ta path Ta Ta -Backend device for the serial port. -Either the pathname of a character device or -.Dq stdio -to use standard input and output of the -.Xr bhyve 1M -process. -.El -.Ss Host Bridge Settings -Host Bridge devices use the following settings. -When configuring parameters, either the -.Va model -by itself, or both of -.Va vendor -and -.Va devid -must be specified. -.Bl -column "vendor" "integer" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va model Ta string Ta netapp Ta -Specify a hostbridge model to emulate. -Valid model strings, and their associated vendor and device IDs are: -.Sy amd Pq 0x1022/0x7432 , -.Sy netapp Pq 0x1275/0x1275 , -.Sy i440fx Pq 0x8086/0x1237 -and -.Sy q35 Pq 0x8086/0x29b0 . -.It Va vendor Ta integer Ta 0x1275 Ta -PCI vendor ID. -.It Va devid Ta integer Ta 0x1275 Ta -PCI device ID. -.El -.Ss 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 -.Dq port. Ns Va N -under the controller's device node. -The -.Va 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: -.Bl -column "model" "integer" "generated" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va type Ta string Ta Ta -The type of storage device to emulate. -Must be set to either -.Dq cd -or -.Dq hd . -.It Va nmrr Ta integer Ta 0 Ta -Nominal Media Rotation Rate, also known as RPM. -A value 1 of indicates a device with no rate such as a Solid State Disk. -.It Va ser Ta string Ta generated Ta -Serial number of up to twenty characters. -A default serial number is generated using a hash of the backing -store's pathname. -.It Va rev Ta string Ta 001 Ta -Revision number of up to eight characters. -.It Va model Ta string Ta Ta -Model number of up to forty characters. -Separate default model strings are used for -.Dq cd -and -.Dq hd -device types. -.El -.Ss Frame Buffer Settings -.Bl -column "password" "[IP:]port" "127.0.0.1:5900" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va wait Ta bool Ta false Ta -Wait for a remote connection before starting the VM. -.It Va rfb Ta Oo Ar IP Ns \&: Oc Ns Ar port Ta 127.0.0.1:5900 Ta -TCP address to listen on for remote connections. -The IP address must be given as a numeric address. -IPv6 addresses must be enclosed in square brackets and -support scoped identifiers as described in -.Xr getaddrinfo 3SOCKET . -A bare port number may be given in which case the IPv4 -localhost address is used. -.It Va unix Ta string Ta Ta -UNIX socket to listen on for VNC connections. -.It Va vga Ta string Ta io Ta -VGA configuration. -More details are provided in -.Xr bhyve 1M . -.It Va w Ta integer Ta 1024 Ta -Frame buffer width in pixels. -.It Va h Ta integer Ta 768 Ta -Frame buffer height in pixels. -.It Va password Ta string Ta Ta -Password to use for VNC authentication. -This type of authentication is known to be cryptographically weak and is not -intended for use on untrusted networks. -.El -.Ss LPC Device Settings -The LPC bridge stores its configuration under a top-level -.Va lpc -node rather than under the PCI LPC device's node. -The following nodes are available under -.Va lpc : -.Bl -column "pc-testdev" "Format" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va bootrom Ta path Ta Ta -Path to a boot ROM. -The contents of this file are copied into the guest's -memory ending just before the 4GB physical address. -If a boot ROM is present, a firmware interface device is -also enabled for use by the boot ROM. -.It Va com1 Ta node Ta Ta -Settings for the COM1 serial port device. -.It Va com2 Ta node Ta Ta -Settings for the COM2 serial port device. -.It Va com3 Ta node Ta Ta -Settings for the COM3 serial port device. -.It Va com4 Ta node Ta Ta -Settings for the COM4 serial port device. -.It Va pc-testdev Ta bool Ta false Ta -Enable the PC debug/test device. -.El -.Ss NVMe Controller Settings -Each NVMe controller supports a single storage device. -The device can be backed either by a memory disk described by the -.Va ram -variable, or a block device using the block device settings described above. -In addition, each controller supports the following settings: -.Bl -column "ioslots" "Format" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va maxq Ta integer Ta 16 Ta -Maximum number of I/O submission and completion queue pairs. -.It Va qsz Ta integer Ta 2058 Ta -Number of elements in each I/O queue. -.It Va ioslots Ta integer Ta 8 Ta -Maximum number of concurrent I/O requests. -.It Va sectsz Ta integer Ta Ta -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. -.It Va ser Ta string Ta Ta -Serial number of up to twenty characters. -A default serial number is generated using a hash of the device's PCI address. -.It Va eui64 Ta integer Ta Ta -IEEE Extended Unique Identifier. -If an EUI is not provided, a default is generated using a checksum of the -device's PCI address. -.It Va dsm Ta string Ta auto Ta -Whether or not to advertise Dataset Management (DSM) support. -One of -.Dq auto , -.Dq enable , -or -.Dq disable . -The -.Dq auto -setting only advertises support if the backing store supports -resource freeing, for example via TRIM. -.It Va ram Ta integer Ta Ta -If set, allocate a memory disk as the backing store. -The value of this variable is the size of the memory disk in megabytes. -.El -.Ss PCI Passthrough Settings -.Bl -column "Name" "integer" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va path Ta string Ta Ta -Path to a PCI passthrough device in the form -.Pa /dev/ppt Ns Ar N -where -.Ar N -is the device number. -.El -.Ss VirtIO 9p Settings -Each VirtIO 9p device exposes a single filesystem from a host path. -.Bl -column "sharename" "Format" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va sharename Ta string Ta Ta -The share name exposed to the guest. -.It Va path Ta path Ta Ta -The path of a directory on the host to export to the guest. -.It Va ro Ta bool Ta false Ta -If true, the guest filesystem is read-only. -.El -.Ss VirtIO Block Device Settings -In addition to the block device settings described above, each -VirtIO block device supports the following settings: -.Bl -column "model" "integer" "generated" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va ser Ta string Ta generated Ta -Serial number of up to twenty characters. -A default serial number is generated using a hash of the backing -store's pathname. -.El -.Ss VirtIO Console Device Settings -Each VirtIO Console device contains one or more console ports. -Each port stores its settings in a node named -.Dq port. Ns Va N -under the controller's device node. -The -.Va N -values are formatted as successive decimal values starting with 0. -Each port supports the following settings: -.Bl -column "Name" "Format" "Default" -.It Sy Name Ta Sy Format Ta Sy Default Ta Sy Description -.It Va name Ta string Ta Ta -The name of the port exposed to the guest. -.It Va path Ta path Ta Ta -The path of a UNIX domain socket providing the host connection for the port. -.El -.Sh SEE ALSO -.Xr bhyve 1M , -.Xr strtoul 3C , -.Xr getaddrinfo 3SOCKET |