usr.sbin/bhyve/bhyve.8

   1 .\" Copyright (c) 2013 Peter Grehan
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd August 19, 2022
  28 .Dt BHYVE 8
  29 .Os
  30 .Sh NAME
  31 .Nm bhyve
  32 .Nd "run a guest operating system inside a virtual machine"
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl AaCDeHhPSuWwxY
  36 .Oo
  37 .Sm off
  38 .Fl c\~
  39 .Oo
  40 .Op Cm cpus=
  41 .Ar numcpus
  42 .Oc
  43 .Op Cm ,sockets= Ar n
  44 .Op Cm ,cores= Ar n
  45 .Op Cm ,threads= Ar n
  46 .Oc
  47 .Sm on
  48 .Oo
  49 .Sm off
  50 .Fl G\~
  51 .Oo Ar w Oc
  52 .Oo Ar bind_address Cm \&: Oc
  53 .Ar port
  54 .Sm on
  55 .Oc
  56 .Op Fl k Ar config_file
  57 .Op Fl K Ar layout
  58 .Oo Fl l
  59 .Sm off
  60 .Ar lpcdev Op Cm \&, Ar conf
  61 .Sm on
  62 .Oc
  63 .Sm off
  64 .Oo Fl m\~
  65 .Ar memsize
  66 .Oo
  67 .Cm K | Cm k | Cm M | Cm m | Cm G | Cm g | Cm T | Cm t
  68 .Oc
  69 .Sm on
  70 .Oc
  71 .Op Fl o Ar var Ns Cm = Ns Ar value
  72 .Op Fl p Ar vcpu Ns Cm \&: Ns Ar hostcpu
  73 .Op Fl r Ar file
  74 .Sm off
  75 .Oo Fl s\~
  76 .Ar slot Cm \&, Ar emulation Op Cm \&, Ar conf
  77 .Sm on
  78 .Oc
  79 .Op Fl U Ar uuid
  80 .Ar vmname
  81 .Nm
  82 .Fl l Cm help
  83 .Nm
  84 .Fl s Cm help
  85 .Sh DESCRIPTION
  86 .Nm
  87 is a hypervisor that runs guest operating systems inside a
  88 virtual machine.
  89 .Pp
  90 Parameters such as the number of virtual CPUs, amount of guest memory, and
  91 I/O connectivity can be specified with command-line parameters.
  92 .Pp
  93 If not using a boot ROM, the guest operating system must be loaded with
  94 .Xr bhyveload 8
  95 or a similar boot loader before running
  96 .Nm ,
  97 otherwise, it is enough to run
  98 .Nm
  99 with a boot ROM of choice.
 100 .Pp
 101 .Nm
 102 runs until the guest operating system reboots or an unhandled hypervisor
 103 exit is detected.
 104 .Sh OPTIONS
 105 .Bl -tag -width 10n
 106 .It Fl A
 107 Generate ACPI tables.
 108 Required for
 109 .Fx Ns /amd64
 110 guests.
 111 .It Fl a
 112 The guest's local APIC is configured in xAPIC mode.
 113 The xAPIC mode is the default setting so this option is redundant.
 114 It will be deprecated in a future version.
 115 .It Fl C
 116 Include guest memory in core file.
 117 .It Fl c Op Ar setting ...
 118 Number of guest virtual CPUs
 119 and/or the CPU topology.
 120 The default value for each of
 121 .Ar numcpus ,
 122 .Ar sockets ,
 123 .Ar cores ,
 124 and
 125 .Ar threads
 126 is 1.
 127 The current maximum number of guest virtual CPUs is 16.
 128 If
 129 .Ar numcpus
 130 is not specified then it will be calculated from the other arguments.
 131 The topology must be consistent in that the
 132 .Ar numcpus
 133 must equal the product of
 134 .Ar sockets ,
 135 .Ar cores ,
 136 and
 137 .Ar threads .
 138 If a
 139 .Ar setting
 140 is specified more than once the last one has precedence.
 141 .It Fl D
 142 Destroy the VM on guest initiated power-off.
 143 .It Fl e
 144 Force
 145 .Nm
 146 to exit when a guest issues an access to an I/O port that is not emulated.
 147 This is intended for debug purposes.
 148 .It Fl G Xo
 149 .Sm off
 150 .Oo Ar w Oc
 151 .Oo Ar bind_address Cm \&: Oc
 152 .Ar port
 153 .Sm on
 154 .Xc
 155 Start a debug server that uses the GDB protocol to export guest state to a
 156 debugger.
 157 An IPv4 TCP socket will be bound to the supplied
 158 .Ar bind_address
 159 and
 160 .Ar port
 161 to listen for debugger connections.
 162 Only a single debugger may be attached to the debug server at a time.
 163 If the option begins with
 164 .Sq w ,
 165 .Nm
 166 will pause execution at the first instruction waiting for a debugger to attach.
 167 .It Fl H
 168 Yield the virtual CPU thread when a HLT instruction is detected.
 169 If this option is not specified, virtual CPUs will use 100% of a host CPU.
 170 .It Fl h
 171 Print help message and exit.
 172 .It Fl k Ar config_file
 173 Set configuration variables from a simple, key-value config file.
 174 Each line of the config file is expected to consist of a config variable
 175 name, an equals sign
 176 .It Fl K Ar layout
 177 Specify the keyboard layout.
 178 The value that can be specified sets the file name in
 179 .Ar /usr/share/bhyve/kbdlayout .
 180 This specification only works when loaded with UEFI mode for VNC.
 181 When using a VNC client that supports QEMU Extended Key Event Message (e.g. TigerVNC), this option isn't needed.
 182 When using a VNC client that doesn't support QEMU Extended Key Event Message (e.g. tightVNC), the layout defaults to the US keyboard unless specified otherwise.
 183 .Pq Sq = ,
 184 and a value.
 185 No spaces are permitted between the variable name, equals sign, or
 186 value.
 187 Blank lines and lines starting with
 188 .Sq #
 189 are ignored.
 190 See
 191 .Xr bhyve_config 5
 192 for more details.
 193 .It Fl l Cm help
 194 Print a list of supported LPC devices.
 195 .It Fl l Ar lpcdev Ns Op Cm \&, Ns Ar conf
 196 Allow devices behind the LPC PCI-ISA bridge to be configured.
 197 The only supported devices are the TTY-class devices
 198 .Cm com1 , com2 , com3 ,
 199 and
 200 .Cm com4 ,
 201 the boot ROM device
 202 .Cm bootrom ,
 203 and the debug/test device
 204 .Cm pc-testdev .
 205 .Pp
 206 The possible values for the
 207 .Ar conf
 208 argument are listed in the
 209 .Fl s
 210 flag description.
 211 .It Xo
 212 .Fl m Ar memsize Ns Oo
 213 .Sm off
 214 .Cm K | k | M | m | G | g | T | t
 215 .Sm on
 216 .Oc
 217 .Xc
 218 Set the guest physical memory size
 219 This must be the same size that was given to
 220 .Xr bhyveload 8 .
 221 .Pp
 222 The size argument may be suffixed with one of
 223 .Cm K , M , G
 224 or
 225 .Cm T
 226 (either upper or lower case)
 227 to indicate a multiple of kilobytes, megabytes, gigabytes, or terabytes.
 228 If no suffix is given, the value is assumed to be in megabytes.
 229 .Pp
 230 The default is 256M.
 231 .It Fl o Ar var Ns Cm = Ns Ar value
 232 Set the configuration variable
 233 .Ar var
 234 to
 235 .Ar value .
 236 .It Fl P
 237 Force the guest virtual CPU to exit when a PAUSE instruction is detected.
 238 .It Fl p Ar vcpu Ns Cm \& : Ns Ar hostcpu
 239 Pin guest's virtual CPU
 240 .Em vcpu
 241 to
 242 .Em hostcpu .
 243 .It Fl r Ar file
 244 Resume a guest from a snapshot.
 245 The guest memory contents are restored from
 246 .Ar file ,
 247 and the guest device and vCPU state are restored from the file
 248 .Dq Ar file Ns .kern .
 249 .Pp
 250 Note that the current snapshot file format requires that the configuration of
 251 devices in the new VM match the VM from which the snapshot was taken by specifying the
 252 same
 253 .Fl s
 254 and
 255 .Fl l
 256 options.
 257 The count of vCPUs and memory configuration are read from the snapshot.
 258 .It Fl S
 259 Wire guest memory.
 260 .It Fl s Cm help
 261 Print a list of supported PCI devices.
 262 .It Fl s Ar slot Ns Cm \&, Ns Ar emulation Ns Op Cm \&, Ns Ar conf
 263 Configure a virtual PCI slot and function.
 264 .Pp
 265 .Nm
 266 provides PCI bus emulation and virtual devices that can be attached to
 267 slots on the bus.
 268 There are 32 available slots, with the option of providing up to 8 functions
 269 per slot.
 270 .Pp
 271 The
 272 .Ar slot
 273 can be specified in one of the following formats:
 274 .Pp
 275 .Bl -bullet -compact
 276 .It
 277 .Ar pcislot
 278 .It
 279 .Sm off
 280 .Ar pcislot Cm \&: Ar function
 281 .Sm on
 282 .It
 283 .Sm off
 284 .Ar bus Cm \&: Ar pcislot Cm \&: Ar function
 285 .Sm on
 286 .El
 287 .Pp
 288 The
 289 .Ar pcislot
 290 value is 0 to 31.
 291 The optional
 292 .Ar function
 293 value is 0 to 7.
 294 The optional
 295 .Ar bus
 296 value is 0 to 255.
 297 If not specified, the
 298 .Ar function
 299 value defaults to 0.
 300 If not specified, the
 301 .Ar bus
 302 value defaults to 0.
 303 .Pp
 304 The
 305 .Ar emulation
 306 argument
 307 can be one of the following:
 308 .Bl -tag -width "amd_hostbridge"
 309 .It Cm hostbridge
 310 A simple host bridge.
 311 This is usually configured at slot 0, and is required by most guest
 312 operating systems.
 313 .It Cm amd_hostbridge
 314 Emulation identical to
 315 .Cm hostbridge
 316 using a PCI vendor ID of AMD.
 317 .It Cm passthru
 318 PCI pass-through device.
 319 .It Cm virtio-net
 320 Virtio network interface.
 321 .It Cm virtio-blk
 322 Virtio block storage interface.
 323 .It Cm virtio-scsi
 324 Virtio SCSI interface.
 325 .It Cm virtio-9p
 326 Virtio 9p (VirtFS) interface.
 327 .It Cm virtio-rnd
 328 Virtio RNG interface.
 329 .It Cm virtio-console
 330 Virtio console interface, which exposes multiple ports
 331 to the guest in the form of simple char devices for simple IO
 332 between the guest and host userspaces.
 333 .It Cm virtio-input
 334 Virtio input interface.
 335 .It Cm ahci
 336 AHCI controller attached to arbitrary devices.
 337 .It Cm ahci-cd
 338 AHCI controller attached to an ATAPI CD/DVD.
 339 .It Cm ahci-hd
 340 AHCI controller attached to a SATA hard drive.
 341 .It Cm e1000
 342 Intel e82545 network interface.
 343 .It Cm uart
 344 PCI 16550 serial device.
 345 .It Cm lpc
 346 LPC PCI-ISA bridge with COM1, COM2, COM3, and COM4 16550 serial ports,
 347 a boot ROM, and,
 348 optionally, the debug/test device.
 349 The LPC bridge emulation can only be configured on bus 0.
 350 .It Cm fbuf
 351 Raw framebuffer device attached to VNC server.
 352 .It Cm xhci
 353 eXtensible Host Controller Interface (xHCI) USB controller.
 354 .It Cm nvme
 355 NVM Express (NVMe) controller.
 356 .It Cm hda
 357 High Definition Audio Controller.
 358 .El
 359 .Pp
 360 The optional parameter
 361 .Ar conf
 362 describes the backend for device emulations.
 363 If
 364 .Ar conf
 365 is not specified, the device emulation has no backend and can be
 366 considered unconnected.
 367 .Pp
 368 Network device backends:
 369 .Sm off
 370 .Bl -bullet
 371 .It
 372 .Xo
 373 .Cm tap Ar N
 374 .Op Cm \&,mac= Ar xx:xx:xx:xx:xx:xx
 375 .Op Cm \&,mtu= Ar N
 376 .Xc
 377 .It
 378 .Xo
 379 .Cm vmnet Ar N
 380 .Op Cm \&,mac= Ar xx:xx:xx:xx:xx:xx
 381 .Op Cm \&,mtu= Ar N
 382 .Xc
 383 .It
 384 .Xo
 385 .Cm netgraph,path= Ar ADDRESS Cm \&,peerhook= Ar HOOK
 386 .Op Cm \&,socket= Ar NAME
 387 .Op Cm \&,hook= Ar HOOK
 388 .Op Cm \&,mac= Ar xx:xx:xx:xx:xx:xx
 389 .Op Cm \&,mtu= Ar N
 390 .Xc
 391 .El
 392 .Sm on
 393 .Pp
 394 If
 395 .Cm mac
 396 is not specified, the MAC address is derived from a fixed OUI and the
 397 remaining bytes from an MD5 hash of the slot and function numbers and
 398 the device name.
 399 .Pp
 400 The MAC address is an ASCII string in
 401 .Xr ethers 5
 402 format.
 403 .Pp
 404 With
 405 .Cm virtio-net
 406 devices, the
 407 .Cm mtu
 408 parameter can be specified to inform the guest about the largest MTU
 409 that should be allowed, expressed in bytes.
 410 .Pp
 411 With
 412 .Cm netgraph
 413 backend, the
 414 .Cm path
 415 and
 416 .Cm peerhook
 417 parameters must be specified to set the destination node and corresponding hook.
 418 The optional parameters
 419 .Cm socket
 420 and
 421 .Cm hook
 422 may be used to set the
 423 .Xr ng_socket 4
 424 node name and source hook.
 425 The
 426 .Ar ADDRESS ,
 427 .Ar HOOK ,
 428 and
 429 .Ar NAME
 430 must comply with
 431 .Xr netgraph 4
 432 addressing rules.
 433 .Pp
 434 Block storage device backends:
 435 .Sm off
 436 .Bl -bullet
 437 .It
 438 .Ar /filename Op Cm \&, Ar block-device-options
 439 .It
 440 .Ar /dev/xxx Op Cm \&, Ar block-device-options
 441 .El
 442 .Sm on
 443 .Pp
 444 The
 445 .Ar block-device-options
 446 are:
 447 .Bl -tag -width 10n
 448 .It Cm nocache
 449 Open the file with
 450 .Dv O_DIRECT .
 451 .It Cm direct
 452 Open the file using
 453 .Dv O_SYNC .
 454 .It Cm ro
 455 Force the file to be opened read-only.
 456 .It Cm sectorsize= Ns Ar logical Ns Oo Cm \&/ Ns Ar physical Oc
 457 Specify the logical and physical sector sizes of the emulated disk.
 458 The physical sector size is optional and is equal to the logical sector size
 459 if not explicitly specified.
 460 .It Cm nodelete
 461 Disable emulation of guest trim requests via
 462 .Dv DIOCGDELETE
 463 requests.
 464 .El
 465 .Pp
 466 SCSI device backends:
 467 .Sm off
 468 .Bl -bullet
 469 .It
 470 .Pa /dev/cam/ctl Oo Ar pp Cm \&. Ar vp Oc Oo Cm \&, Ar scsi-device-options Oc
 471 .El
 472 .Sm on
 473 .Pp
 474 The
 475 .Ar scsi-device-options
 476 are:
 477 .Bl -tag -width 10n
 478 .It Cm iid= Ns Ar IID
 479 Initiator ID to use when sending requests to specified CTL port.
 480 The default value is 0.
 481 .El
 482 .Pp
 483 9P device backends:
 484 .Sm off
 485 .Bl -bullet
 486 .It
 487 .Ar sharename Cm = Ar /path/to/share Op Cm \&, Ar 9p-device-options
 488 .El
 489 .Sm on
 490 .Pp
 491 The
 492 .Ar 9p-device-options
 493 are:
 494 .Bl -tag -width 10n
 495 .It Cm ro
 496 Expose the share in read-only mode.
 497 .El
 498 .Pp
 499 TTY device backends:
 500 .Bl -tag -width 10n
 501 .It Cm stdio
 502 Connect the serial port to the standard input and output of
 503 the
 504 .Nm
 505 process.
 506 .It Ar /dev/xxx
 507 Use the host TTY device for serial port I/O.
 508 .El
 509 .Pp
 510 Boot ROM device backends:
 511 .Bl -tag -width 10n
 512 .It Ar romfile Ns Op Cm \&, Ns Ar varfile
 513 Map
 514 .Ar romfile
 515 in the guest address space reserved for boot firmware.
 516 If
 517 .Ar varfile
 518 is provided, that file is also mapped in the boot firmware guest
 519 address space, and any modifications the guest makes will be saved
 520 to that file.
 521 .El
 522 .Pp
 523 Pass-through device backends:
 524 .Sm off
 525 .Bl -bullet
 526 .It
 527 .Cm ppt Ar N Oo , Ar passthru-device-options Oc
 528 .It
 529 .Ns Ar bus Cm \&/ Ar slot Cm \&/ Ar function
 530 .Op , Ar passthru-device-options
 531 .It
 532 .Cm pci Ar bus Cm : Ar slot Cm : Ns Ar function
 533 .Op , Ar passthru-device-options
 534 .El
 535 .Sm on
 536 .Pp
 537 Connect to a PCI device on the host either named ppt
 538 .Ns Ar N
 539 or at the selector described by
 540 .Ar slot ,
 541 .Ar bus ,
 542 and
 543 .Ar function
 544 numbers.
 545 .Pp
 546 The
 547 .Ar passthru-device-options
 548 are:
 549 .Bl -tag -width 10n
 550 .It Cm rom= Ns Ar romfile
 551 Add
 552 .Ar romfile
 553 as option ROM to the PCI device.
 554 The ROM will be loaded by firmware and should be capable of initializing the device.
 555 .El
 556 .Pp
 557 Guest memory must be wired using the
 558 .Fl S
 559 option when a pass-through device is configured.
 560 .Pp
 561 The host device must have been reserved at boot-time using the
 562 .Va pptdevs
 563 loader variable as described in
 564 .Xr vmm 4 .
 565 .Pp
 566 Virtio console device backends:
 567 .Bl -bullet
 568 .Sm off
 569 .It
 570 .Cm port1= Ns Ar /path/to/port1.sock Ns Op Cm ,port Ns Ar N Cm \&= Ns Ar /path/to/port2.sock No \~ Ar ...
 571 .Sm on
 572 .El
 573 .Pp
 574 A maximum of 16 ports per device can be created.
 575 Every port is named and corresponds to a Unix domain socket created by
 576 .Nm .
 577 .Nm
 578 accepts at most one connection per port at a time.
 579 .Pp
 580 Limitations:
 581 .Bl -bullet
 582 .It
 583 Due to lack of destructors in
 584 .Nm ,
 585 sockets on the filesystem must be cleaned up manually after
 586 .Nm
 587 exits.
 588 .It
 589 There is no way to use the
 590 .Dq console port
 591 feature, nor the console port
 592 resize at present.
 593 .It
 594 Emergency write is advertised, but no-op at present.
 595 .El
 596 .Pp
 597 Virtio input device backends:
 598 .Bl -tag -width 10n
 599 .It Ar /dev/input/eventX
 600 Send input events of
 601 .Ar /dev/input/eventX
 602 to guest by VirtIO Input Interface.
 603 .El
 604 .Pp
 605 Framebuffer devices backends:
 606 .Bl -bullet
 607 .Sm off
 608 .It
 609 .Op Cm rfb= Ar ip-and-port
 610 .Op Cm ,w= Ar width
 611 .Op Cm ,h= Ar height
 612 .Op Cm ,vga= Ar vgaconf
 613 .Op Cm ,wait
 614 .Op Cm ,password= Ar password
 615 .Sm on
 616 .El
 617 .Pp
 618 Configuration options are defined as follows:
 619 .Bl -tag -width 10n
 620 .It Cm rfb= Ns Ar ip-and-port Pq or Cm tcp= Ns Ar ip-and-port
 621 An IP address and a port VNC should listen on.
 622 There are two formats:
 623 .Pp
 624 .Bl -bullet -compact
 625 .It
 626 .Sm off
 627 .Op Ar IPv4 Cm \&:
 628 .Ar port
 629 .Sm on
 630 .It
 631 .Sm off
 632 .Cm \&[ Ar IPv6%zone Cm \&] Cm \&: Ar port
 633 .Sm on
 634 .El
 635 .Pp
 636 The default is to listen on localhost IPv4 address and default VNC port 5900.
 637 An IPv6 address must be enclosed in square brackets and may contain an
 638 optional zone identifier.
 639 .It Cm w= Ns Ar width No and Cm h= Ns Ar height
 640 A display resolution, width and height, respectively.
 641 If not specified, a default resolution of 1024x768 pixels will be used.
 642 Minimal supported resolution is 640x480 pixels,
 643 and maximum is 1920x1200 pixels.
 644 .It Cm vga= Ns Ar vgaconf
 645 Possible values for this option are
 646 .Cm io
 647 (default),
 648 .Cm on
 649 , and
 650 .Cm off .
 651 PCI graphics cards have a dual personality in that they are
 652 standard PCI devices with BAR addressing, but may also
 653 implicitly decode legacy VGA I/O space
 654 .Pq Ad 0x3c0-3df
 655 and memory space
 656 .Pq 64KB at Ad 0xA0000 .
 657 The default
 658 .Cm io
 659 option should be used for guests that attempt to issue BIOS calls which result
 660 in I/O port queries, and fail to boot if I/O decode is disabled.
 661 .Pp
 662 The
 663 .Cm on
 664 option should be used along with the CSM BIOS capability in UEFI
 665 to boot traditional BIOS guests that require the legacy VGA I/O and
 666 memory regions to be available.
 667 .Pp
 668 The
 669 .Cm off
 670 option should be used for the UEFI guests that assume that
 671 VGA adapter is present if they detect the I/O ports.
 672 An example of such a guest is
 673 .Ox
 674 in UEFI mode.
 675 .Pp
 676 Please refer to the
 677 .Nm
 678 .Fx
 679 wiki page
 680 .Pq Lk https://wiki.freebsd.org/bhyve
 681 for configuration notes of particular guests.
 682 .It Cm wait
 683 Instruct
 684 .Nm
 685 to only boot upon the initiation of a VNC connection, simplifying the
 686 installation of operating systems that require immediate keyboard input.
 687 This can be removed for post-installation use.
 688 .It Cm password= Ns Ar password
 689 This type of authentication is known to be cryptographically weak and is not
 690 intended for use on untrusted networks.
 691 Many implementations will want to use stronger security, such as running
 692 the session over an encrypted channel provided by IPsec or SSH.
 693 .El
 694 .Pp
 695 xHCI USB device backends:
 696 .Bl -tag -width 10n
 697 .It Cm tablet
 698 A USB tablet device which provides precise cursor synchronization
 699 when using VNC.
 700 .El
 701 .Pp
 702 NVMe device backends:
 703 .Bl -bullet
 704 .Sm off
 705 .It
 706 .Ar devpath
 707 .Op Cm ,maxq= Ar #
 708 .Op Cm ,qsz= Ar #
 709 .Op Cm ,ioslots= Ar #
 710 .Op Cm ,sectsz= Ar #
 711 .Op Cm ,ser= Ar #
 712 .Op Cm ,eui64= Ar #
 713 .Op Cm ,dsm= Ar opt
 714 .Sm on
 715 .El
 716 .Pp
 717 Configuration options are defined as follows:
 718 .Bl -tag -width 10n
 719 .It Ar devpath
 720 Accepted device paths are:
 721 .Ar /dev/blockdev
 722 or
 723 .Ar /path/to/image
 724 or
 725 .Cm ram= Ns Ar size_in_MiB .
 726 .It Cm maxq
 727 Max number of queues.
 728 .It Cm qsz
 729 Max elements in each queue.
 730 .It Cm ioslots
 731 Max number of concurrent I/O requests.
 732 .It Cm sectsz
 733 Sector size (defaults to blockif sector size).
 734 .It Cm ser
 735 Serial number with maximum 20 characters.
 736 .It Cm eui64
 737 IEEE Extended Unique Identifier (8 byte value).
 738 .It Cm dsm
 739 DataSet Management support.
 740 Supported values are:
 741 .Cm auto , enable ,
 742 and
 743 .Cm disable .
 744 .El
 745 .Pp
 746 AHCI device backends:
 747 .Bl -bullet
 748 .It
 749 .Sm off
 750 .Op Oo Cm hd\&: | cd\&: Oc Ar path
 751 .Op Cm ,nmrr= Ar nmrr
 752 .Op Cm ,ser= Ar #
 753 .Op Cm ,rev= Ar #
 754 .Op Cm ,model= Ar #
 755 .Sm on
 756 .El
 757 .Pp
 758 Configuration options are defined as follows:
 759 .Bl -tag -width 10n
 760 .It Cm nmrr
 761 Nominal Media Rotation Rate, known as RPM.
 762 Value 1 will indicate device as Solid State Disk.
 763 Default value is 0, not report.
 764 .It Cm ser
 765 Serial Number with maximum 20 characters.
 766 .It Cm rev
 767 Revision Number with maximum 8 characters.
 768 .It Cm model
 769 Model Number with maximum 40 characters.
 770 .El
 771 .Pp
 772 HD Audio device backends:
 773 .Bl -bullet
 774 .It
 775 .Sm off
 776 .Op Cm play= Ar playback
 777 .Op Cm ,rec= Ar recording
 778 .Sm on
 779 .El
 780 .Pp
 781 Configuration options are defined as follows:
 782 .Bl -tag -width 10n
 783 .It Cm play
 784 Playback device, typically
 785 .Ar /dev/dsp0 .
 786 .It Cm rec
 787 Recording device, typically
 788 .Ar /dev/dsp0 .
 789 .El
 790 .It Fl U Ar uuid
 791 Set the universally unique identifier
 792 .Pq UUID
 793 in the guest's System Management BIOS System Information structure.
 794 By default a UUID is generated from the host's hostname and
 795 .Ar vmname .
 796 .It Fl u
 797 RTC keeps UTC time.
 798 .It Fl W
 799 Force virtio PCI device emulations to use MSI interrupts instead of MSI-X
 800 interrupts.
 801 .It Fl w
 802 Ignore accesses to unimplemented Model Specific Registers (MSRs).
 803 This is intended for debug purposes.
 804 .It Fl x
 805 The guest's local APIC is configured in x2APIC mode.
 806 .It Fl Y
 807 Disable MPtable generation.
 808 .It Ar vmname
 809 Alphanumeric name of the guest.
 810 This should be the same as that created by
 811 .Xr bhyveload 8 .
 812 .El
 813 .Sh CONFIGURATION VARIABLES
 814 .Nm
 815 uses an internal tree of configuration variables to describe global and
 816 per-device settings.
 817 When
 818 .Nm
 819 starts,
 820 it parses command line options (including config files) in the order given
 821 on the command line.
 822 Each command line option sets one or more configuration variables.
 823 For example,
 824 the
 825 .Fl s
 826 option creates a new tree node for a PCI device and sets one or more variables
 827 under that node including the device model and device model-specific variables.
 828 Variables may be set multiple times during this parsing stage with the final
 829 value overriding previous values.
 830 .Pp
 831 Once all of the command line options have been processed,
 832 the configuration values are frozen.
 833 .Nm
 834 then uses the value of configuration values to initialize device models
 835 and global settings.
 836 .Pp
 837 More details on configuration variables can be found in
 838 .Xr bhyve_config 5 .
 839 .Sh DEBUG SERVER
 840 The current debug server provides limited support for debuggers.
 841 .Ss Registers
 842 Each virtual CPU is exposed to the debugger as a thread.
 843 .Pp
 844 General purpose registers can be queried for each virtual CPU, but other
 845 registers such as floating-point and system registers cannot be queried.
 846 .Ss Memory
 847 Memory (including memory mapped I/O regions) can be read and written by the debugger.
 848 Memory operations use virtual addresses that are resolved to physical addresses
 849 via the current virtual CPU's active address translation.
 850 .Ss Control
 851 The running guest can be interrupted by the debugger at any time
 852 .Pq for example, by pressing Ctrl-C in the debugger .
 853 .Pp
 854 Single stepping is only supported on Intel CPUs supporting the MTRAP VM exit.
 855 .Pp
 856 Breakpoints are supported on Intel CPUs that support single stepping.
 857 Note that continuing from a breakpoint while interrupts are enabled in the
 858 guest may not work as expected due to timer interrupts firing while single
 859 stepping over the breakpoint.
 860 .Sh SIGNAL HANDLING
 861 .Nm
 862 deals with the following signals:
 863 .Pp
 864 .Bl -tag -width SIGTERM -compact
 865 .It SIGTERM
 866 Trigger ACPI poweroff for a VM
 867 .El
 868 .Sh EXIT STATUS
 869 Exit status indicates how the VM was terminated:
 870 .Pp
 871 .Bl -tag -width indent -compact
 872 .It 0
 873 rebooted
 874 .It 1
 875 powered off
 876 .It 2
 877 halted
 878 .It 3
 879 triple fault
 880 .It 4
 881 exited due to an error
 882 .El
 883 .Sh EXAMPLES
 884 If not using a boot ROM, the guest operating system must have been loaded with
 885 .Xr bhyveload 8
 886 or a similar boot loader before
 887 .Xr bhyve 4
 888 can be run.
 889 Otherwise, the boot loader is not needed.
 890 .Pp
 891 To run a virtual machine with 1GB of memory, two virtual CPUs, a virtio
 892 block device backed by the
 893 .Pa /my/image
 894 filesystem image, and a serial port for the console:
 895 .Bd -literal -offset indent
 896 bhyve -c 2 -s 0,hostbridge -s 1,lpc -s 2,virtio-blk,/my/image \\
 897   -l com1,stdio -A -H -P -m 1G vm1
 898 .Ed
 899 .Pp
 900 Run a 24GB single-CPU virtual machine with three network ports, one of which
 901 has a MAC address specified:
 902 .Bd -literal -offset indent
 903 bhyve -s 0,hostbridge -s 1,lpc -s 2:0,virtio-net,tap0 \\
 904   -s 2:1,virtio-net,tap1 \\
 905   -s 2:2,virtio-net,tap2,mac=00:be:fa:76:45:00 \\
 906   -s 3,virtio-blk,/my/image -l com1,stdio \\
 907   -A -H -P -m 24G bigvm
 908 .Ed
 909 .Pp
 910 Run an 8GB quad-CPU virtual machine with 8 AHCI SATA disks, an AHCI ATAPI
 911 CD-ROM, a single virtio network port, an AMD hostbridge, and the console
 912 port connected to an
 913 .Xr nmdm 4
 914 null-modem device.
 915 .Bd -literal -offset indent
 916 bhyve -c 4 \\
 917   -s 0,amd_hostbridge -s 1,lpc \\
 918   -s 1:0,ahci,hd:/images/disk.1,hd:/images/disk.2,\\
 919 hd:/images/disk.3,hd:/images/disk.4,\\
 920 hd:/images/disk.5,hd:/images/disk.6,\\
 921 hd:/images/disk.7,hd:/images/disk.8,\\
 922 cd:/images/install.iso \\
 923   -s 3,virtio-net,tap0 \\
 924   -l com1,/dev/nmdm0A \\
 925   -A -H -P -m 8G
 926 .Ed
 927 .Pp
 928 Run a UEFI virtual machine with a display resolution of 800 by 600 pixels
 929 that can be accessed via VNC at: 0.0.0.0:5900.
 930 .Bd -literal -offset indent
 931 bhyve -c 2 -m 4G -w -H \\
 932   -s 0,hostbridge \\
 933   -s 3,ahci-cd,/path/to/uefi-OS-install.iso \\
 934   -s 4,ahci-hd,disk.img \\
 935   -s 5,virtio-net,tap0 \\
 936   -s 29,fbuf,tcp=0.0.0.0:5900,w=800,h=600,wait \\
 937   -s 30,xhci,tablet \\
 938   -s 31,lpc -l com1,stdio \\
 939   -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \\
 940    uefivm
 941 .Ed
 942 .Pp
 943 Run a UEFI virtual machine with a VNC display that is bound to all IPv6
 944 addresses on port 5900.
 945 .Bd -literal -offset indent
 946 bhyve -c 2 -m 4G -w -H \\
 947   -s 0,hostbridge \\
 948   -s 4,ahci-hd,disk.img \\
 949   -s 5,virtio-net,tap0 \\
 950   -s 29,fbuf,tcp=[::]:5900,w=800,h=600 \\
 951   -s 30,xhci,tablet \\
 952   -s 31,lpc -l com1,stdio \\
 953   -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \\
 954    uefivm
 955 .Ed
 956 .Pp
 957 Run a UEFI virtual machine with a VARS file to save EFI variables.
 958 Note that
 959 .Nm
 960 will write guest modifications to the given VARS file.
 961 Be sure to create a per-guest copy of the template VARS file from
 962 .Pa /usr .
 963 .Bd -literal -offset indent
 964 bhyve -c 2 -m 4g -w -H \\
 965   -s 0,hostbridge \\
 966   -s 31,lpc -p com1,stdio \\
 967   -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI_CODE.fd,BHYVE_UEFI_VARS.fd
 968    uefivm
 969 .Ed
 970 .Sh SEE ALSO
 971 .Xr bhyve 4 ,
 972 .Xr netgraph 4 ,
 973 .Xr ng_socket 4 ,
 974 .Xr nmdm 4 ,
 975 .Xr vmm 4 ,
 976 .Xr bhyve_config 5 ,
 977 .Xr ethers 5 ,
 978 .Xr bhyvectl 8 ,
 979 .Xr bhyveload 8
 980 .Pp
 981 .Rs
 982 .%A Intel
 983 .%B 64 and IA-32 Architectures Software Developer’s Manual
 984 .%V Volume 3
 985 .Re
 986 .Sh HISTORY
 987 .Nm
 988 first appeared in
 989 .Fx 10.0 .
 990 .Sh AUTHORS
 991 .An Neel Natu Aq Mt neel@freebsd.org
 992 .An Peter Grehan Aq Mt grehan@freebsd.org