usr.sbin/bhyve/bhyve_config.5

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