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 April 18, 2021
  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 AabCeHhPSuWwxY
  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 .Op Fl G Ar port
  49 .Op Fl g Ar gdbport
  50 .Oo Fl l
  51 .Sm off
  52 .Ar lpcdev Op Cm \&, Ar conf
  53 .Sm on
  54 .Oc
  55 .Oo Fl m
  56 .Sm off
  57 .Ar memsize
  58 .Oo
  59 .Cm K No | Cm k No | Cm M No | Cm m No | Cm G No | Cm g No | Cm T No | Cm t
  60 .Oc
  61 .Sm on
  62 .Oc
  63 .Op Fl p Ar vcpu Ns Cm \&: Ns Ar hostcpu
  64 .Sm off
  65 .Oo Fl s\~
  66 .Ar slot Cm \&, Ar emulation Op Cm \&, Ar conf
  67 .Sm on
  68 .Oc
  69 .Op Fl U Ar uuid
  70 .Ar vmname
  71 .Nm
  72 .Fl l Cm help
  73 .Nm
  74 .Fl s Cm help
  75 .Sh DESCRIPTION
  76 .Nm
  77 is a hypervisor that runs guest operating systems inside a
  78 virtual machine.
  79 .Pp
  80 Parameters such as the number of virtual CPUs, amount of guest memory, and
  81 I/O connectivity can be specified with command-line parameters.
  82 .Pp
  83 If not using a boot ROM, the guest operating system must be loaded with
  84 .Xr bhyveload 8
  85 or a similar boot loader before running
  86 .Nm ,
  87 otherwise, it is enough to run
  88 .Nm
  89 with a boot ROM of choice.
  90 .Pp
  91 .Nm
  92 runs until the guest operating system reboots or an unhandled hypervisor
  93 exit is detected.
  94 .Sh OPTIONS
  95 .Bl -tag -width 10n
  96 .It Fl A
  97 Generate ACPI tables.
  98 Required for
  99 .Fx Ns /amd64
 100 guests.
 101 .It Fl a
 102 The guest's local APIC is configured in xAPIC mode.
 103 The xAPIC mode is the default setting so this option is redundant.
 104 It will be deprecated in a future version.
 105 .It Fl b
 106 Enable a low-level console device supported by
 107 .Fx
 108 kernels compiled with
 109 .Cd "device bvmconsole" .
 110 This option is deprecated and will be removed in
 111 .Fx 13.0 .
 112 .It Fl C
 113 Include guest memory in core file.
 114 .It Fl c Op Ar setting ...
 115 Number of guest virtual CPUs
 116 and/or the CPU topology.
 117 The default value for each of
 118 .Ar numcpus ,
 119 .Ar sockets ,
 120 .Ar cores ,
 121 and
 122 .Ar threads
 123 is 1.
 124 The current maximum number of guest virtual CPUs is 16.
 125 If
 126 .Ar numcpus
 127 is not specified then it will be calculated from the other arguments.
 128 The topology must be consistent in that the
 129 .Ar numcpus
 130 must equal the product of
 131 .Ar sockets ,
 132 .Ar cores ,
 133 and
 134 .Ar threads .
 135 If a
 136 .Ar setting
 137 is specified more than once the last one has precedence.
 138 .It Fl D
 139 Destroy the VM on guest initiated power-off.
 140 .It Fl e
 141 Force
 142 .Nm
 143 to exit when a guest issues an access to an I/O port that is not emulated.
 144 This is intended for debug purposes.
 145 .It Fl G Ar port
 146 Start a debug server that uses the GDB protocol to export guest state to a
 147 debugger.
 148 An IPv4 TCP socket will be bound to the supplied
 149 .Ar port
 150 to listen for debugger connections.
 151 Only a single debugger may be attached to the debug server at a time.
 152 If
 153 .Ar port
 154 begins with
 155 .Sq w ,
 156 .Nm
 157 will pause execution at the first instruction waiting for a debugger to attach.
 158 .It Fl g Ar gdbport
 159 For
 160 .Fx
 161 kernels compiled with
 162 .Cd "device bvmdebug" ,
 163 allow a remote kernel kgdb to be relayed to the guest kernel gdb stub
 164 via a local IPv4 address and this port.
 165 This option is deprecated and will be removed in
 166 .Fx 13.0 .
 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 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 .Pq Sq = ,
 177 and a value.
 178 No spaces are permitted between the variable name, equals sign, or
 179 value.
 180 Blank lines and lines starting with
 181 .Sq #
 182 are ignored.
 183 .It Fl l Cm help
 184 Print a list of supported LPC devices.
 185 .It Fl l Ar lpcdev Ns Op Cm \&, Ns Ar conf
 186 Allow devices behind the LPC PCI-ISA bridge to be configured.
 187 The only supported devices are the TTY-class devices
 188 .Ar com1
 189 and
 190 .Ar com2 ,
 191 the boot ROM device
 192 .Cm bootrom ,
 193 and the debug/test device
 194 .Cm pc-testdev .
 195 .Pp
 196 The possible values for the
 197 .Ar conf
 198 argument are listed in the
 199 .Fl s
 200 flag description.
 201 .It Xo
 202 .Fl m Ar memsize Ns Oo
 203 .Sm off
 204 .Cm K | k | M | m | G | g | T | t
 205 .Sm on
 206 .Oc
 207 .Xc
 208 Set the guest physical memory size
 209 This must be the same size that was given to
 210 .Xr bhyveload 8 .
 211 .Pp
 212 The size argument may be suffixed with one of
 213 .Cm K , M , G
 214 or
 215 .Cm T
 216 (either upper or lower case)
 217 to indicate a multiple of kilobytes, megabytes, gigabytes, or terabytes.
 218 If no suffix is given, the value is assumed to be in megabytes.
 219 .Pp
 220 The default is 256M.
 221 .It Fl o Ar var Ns Cm = Ns Ar value
 222 Set the configuration variable
 223 .Ar var
 224 to
 225 .Ar value .
 226 .It Fl P
 227 Force the guest virtual CPU to exit when a PAUSE instruction is detected.
 228 .It Fl p Ar vcpu Ns Cm \& : Ns Ar hostcpu
 229 Pin guest's virtual CPU
 230 .Em vcpu
 231 to
 232 .Em hostcpu .
 233 .It Fl P
 234 Force the guest virtual CPU to exit when a PAUSE instruction is detected.
 235 .It Fl S
 236 Wire guest memory.
 237 .It Fl s Cm help
 238 Print a list of supported PCI devices.
 239 .It Fl s Ar slot Ns Cm \&, Ns Ar emulation Ns Op Cm \&, Ns Ar conf
 240 Configure a virtual PCI slot and function.
 241 .Pp
 242 .Nm
 243 provides PCI bus emulation and virtual devices that can be attached to
 244 slots on the bus.
 245 There are 32 available slots, with the option of providing up to 8 functions
 246 per slot.
 247 .Pp
 248 The
 249 .Ar slot
 250 can be specified in one of the following formats:
 251 .Pp
 252 .Bl -bullet -compact
 253 .It
 254 .Ar pcislot
 255 .It
 256 .Sm off
 257 .Ar pcislot Cm \&: Ar function
 258 .Sm on
 259 .It
 260 .Sm off
 261 .Ar bus Cm \&: Ar pcislot Cm \&: Ar function
 262 .Sm on
 263 .El
 264 .Pp
 265 The
 266 .Ar pcislot
 267 value is 0 to 31.
 268 The optional
 269 .Ar function
 270 value is 0 to 7.
 271 The optional
 272 .Ar bus
 273 value is 0 to 255.
 274 If not specified, the
 275 .Ar function
 276 value defaults to 0.
 277 If not specified, the
 278 .Ar bus
 279 value defaults to 0.
 280 .Pp
 281 The
 282 .Ar emulation
 283 argument
 284 can be one of the following:
 285 .Bl -tag -width "amd_hostbridge"
 286 .It Cm hostbridge
 287 A simple host bridge.
 288 This is usually configured at slot 0, and is required by most guest
 289 operating systems.
 290 .It Cm amd_hostbridge
 291 Emulation identical to
 292 .Cm hostbridge
 293 using a PCI vendor ID of AMD.
 294 .It Cm passthru
 295 PCI pass-through device.
 296 .It Cm virtio-net
 297 Virtio network interface.
 298 .It Cm virtio-blk
 299 Virtio block storage interface.
 300 .It Cm virtio-scsi
 301 Virtio SCSI interface.
 302 .It Cm virtio-rnd
 303 Virtio RNG interface.
 304 .It Cm virtio-console
 305 Virtio console interface, which exposes multiple ports
 306 to the guest in the form of simple char devices for simple IO
 307 between the guest and host userspaces.
 308 .It Cm ahci
 309 AHCI controller attached to arbitrary devices.
 310 .It Cm ahci-cd
 311 AHCI controller attached to an ATAPI CD/DVD.
 312 .It Cm ahci-hd
 313 AHCI controller attached to a SATA hard drive.
 314 .It Cm e1000
 315 Intel e82545 network interface.
 316 .It Cm uart
 317 PCI 16550 serial device.
 318 .It Cm lpc
 319 LPC PCI-ISA bridge with COM1, COM2, and 16550 serial ports,
 320 a boot ROM, and,
 321 optionally, the debug/test device.
 322 The LPC bridge emulation can only be configured on bus 0.
 323 .It Cm fbuf
 324 Raw framebuffer device attached to VNC server.
 325 .It Cm xhci
 326 eXtensible Host Controller Interface (xHCI) USB controller.
 327 .It Cm nvme
 328 NVM Express (NVMe) controller.
 329 .El
 330 .Pp
 331 The optional parameter
 332 .Ar conf
 333 describes the backend for device emulations.
 334 If
 335 .Ar conf
 336 is not specified, the device emulation has no backend and can be
 337 considered unconnected.
 338 .Pp
 339 Network backends formats for
 340 .Ar conf :
 341 .Sm off
 342 .Bl -bullet
 343 .It
 344 .Xo
 345 .Cm tap Ar N
 346 .Op Cm \&,mac= Ar xx:xx:xx:xx:xx:xx
 347 .Op Cm \&,mtu= Ar N
 348 .Xc
 349 .It
 350 .Xo
 351 .Cm vmnet Ar N
 352 .Op Cm \&,mac= Ar xx:xx:xx:xx:xx:xx
 353 .Op Cm \&,mtu= Ar N
 354 .Xc
 355 .El
 356 .Sm on
 357 .Pp
 358 With
 359 .Cm virtio-net
 360 devices, the
 361 .Cm mtu
 362 parameter can be specified to inform the guest about the largest MTU
 363 that should be allowed, expressed in bytes.
 364 .Pp
 365 Block storage device backends:
 366 .Sm off
 367 .Bl -bullet
 368 .It
 369 .Ar /filename Op Cm \&, Ar block-device-options
 370 .It
 371 .Ar /dev/xxx Op Cm \&, Ar block-device-options
 372 .El
 373 .Sm on
 374 .Pp
 375 The
 376 .Ar block-device-options
 377 are:
 378 .Bl -tag -width 10n
 379 .It Cm nocache
 380 Open the file with
 381 .Dv O_DIRECT .
 382 .It Cm direct
 383 Open the file using
 384 .Dv O_SYNC .
 385 .It Cm ro
 386 Force the file to be opened read-only.
 387 .It Cm sectorsize= Ns Ar logical Ns Oo Cm \&/ Ns Ar physical Oc
 388 Specify the logical and physical sector sizes of the emulated disk.
 389 The physical sector size is optional and is equal to the logical sector size
 390 if not explicitly specified.
 391 .El
 392 .Pp
 393 SCSI device backends:
 394 .Sm off
 395 .Bl -bullet
 396 .It
 397 .Pa /dev/cam/ctl Oo Ar pp Cm \&. Ar vp Oc Oo Cm \&, Ar scsi-device-options Oc
 398 .El
 399 .Sm on
 400 .Pp
 401 The
 402 .Ar scsi-device-options
 403 are:
 404 .Bl -tag -width 10n
 405 .It Cm iid= Ns Ar IID
 406 Initiator ID to use when sending requests to specified CTL port.
 407 The default value is 0.
 408 .El
 409 .Pp
 410 TTY device backends:
 411 .Bl -tag -width 10n
 412 .It Cm stdio
 413 Connect the serial port to the standard input and output of
 414 the
 415 .Nm
 416 process.
 417 .It Ar /dev/xxx
 418 Use the host TTY device for serial port I/O.
 419 .El
 420 .Pp
 421 Boot ROM device backends:
 422 .Bl -tag -width 10n
 423 .It Ar romfile
 424 Map
 425 .Ar romfile
 426 in the guest address space reserved for boot firmware.
 427 .El
 428 .Pp
 429 Pass-through device backends:
 430 .Bl -tag -width 10n
 431 .It Ns Ar slot Ns Cm \&/ Ns Ar bus Ns Cm \&/ Ns Ar function
 432 Connect to a PCI device on the host at the selector described by
 433 .Ar slot ,
 434 .Ar bus ,
 435 and
 436 .Ar function
 437 numbers.
 438 .El
 439 .Pp
 440 Guest memory must be wired using the
 441 .Fl S
 442 option when a pass-through device is configured.
 443 .Pp
 444 The host device must have been reserved at boot-time using the
 445 .Va pptdevs
 446 loader variable as described in
 447 .Xr vmm 4 .
 448 .Pp
 449 Virtio console device backends:
 450 .Bl -bullet
 451 .Sm off
 452 .It
 453 .Cm port1= Ns Ar /path/to/port1.sock Ns Op Cm ,port Ns Ar N Cm \&= Ns Ar /path/to/port2.sock No \~ Ar ...
 454 .Sm on
 455 .El
 456 .Pp
 457 A maximum of 16 ports per device can be created.
 458 Every port is named and corresponds to a Unix domain socket created by
 459 .Nm .
 460 .Nm
 461 accepts at most one connection per port at a time.
 462 .Pp
 463 Limitations:
 464 .Bl -bullet -offset
 465 .It
 466 Due to lack of destructors in
 467 .Nm ,
 468 sockets on the filesystem must be cleaned up manually after
 469 .Nm
 470 exits.
 471 .It
 472 There is no way to use the
 473 .Dq console port
 474 feature, nor the console port
 475 resize at present.
 476 .It
 477 Emergency write is advertised, but no-op at present.
 478 .El
 479 .Pp
 480 Framebuffer devices backends:
 481 .Bl -bullet
 482 .Sm off
 483 .It
 484 .Op Cm rfb= Ar ip-and-port
 485 .Op Cm ,w= Ar width
 486 .Op Cm ,h= Ar height
 487 .Op Cm ,vga= Ar vgaconf
 488 .Op Cm ,wait
 489 .Op Cm ,password= Ar password
 490 .Sm on
 491 .El
 492 .Pp
 493 Configuration options are defined as follows:
 494 .Bl -tag -width 10n
 495 .It Cm rfb= Ns Ar ip-and-port Pq or Cm tcp= Ns Ar ip-and-port
 496 An IP address and a port VNC should listen on.
 497 There are two formats:
 498 .Pp
 499 .Bl -bullet -compact
 500 .It IPv4
 501 .Sm off
 502 .Op Ar IPv4 Cm \&:
 503 .Ar port
 504 .Sm on
 505 .It IPv6
 506 .Sm off
 507 .Cm \&[ Ar IPv6%zone Cm \&] Cm \&: Ar port
 508 .Sm on
 509 .El
 510 .Pp
 511 The default is to listen on localhost IPv4 address and default VNC port 5900.
 512 An IPv6 address must be enclosed in square brackets and may contain an
 513 optional zone identifier.
 514 .It Cm w= Ns Ar width No and Cm h= Ns Ar height
 515 A display resolution, width and height, respectively.
 516 If not specified, a default resolution of 1024x768 pixels will be used.
 517 Minimal supported resolution is 640x480 pixels,
 518 and maximum is 1920x1200 pixels.
 519 .It Cm vga= Ns Ar vgaconf
 520 Possible values for this option are
 521 .Cm io
 522 (default),
 523 .Cm on
 524 , and
 525 .Cm off .
 526 PCI graphics cards have a dual personality in that they are
 527 standard PCI devices with BAR addressing, but may also
 528 implicitly decode legacy VGA I/O space
 529 .Pq Ad 0x3c0-3df
 530 and memory space
 531 .Pq 64KB at Ad 0xA0000 .
 532 The default
 533 .Cm io
 534 option should be used for guests that attempt to issue BIOS calls which result
 535 in I/O port queries, and fail to boot if I/O decode is disabled.
 536 .Pp
 537 The
 538 .Cm on
 539 option should be used along with the CSM BIOS capability in UEFI
 540 to boot traditional BIOS guests that require the legacy VGA I/O and
 541 memory regions to be available.
 542 .Pp
 543 The
 544 .Cm off
 545 option should be used for the UEFI guests that assume that
 546 VGA adapter is present if they detect the I/O ports.
 547 An example of such a guest is
 548 .Ox
 549 in UEFI mode.
 550 .Pp
 551 Please refer to the
 552 .Nm
 553 .Fx
 554 wiki page
 555 .Pq Lk https://wiki.freebsd.org/bhyve
 556 for configuration notes of particular guests.
 557 .It Cm wait
 558 Instruct
 559 .Nm
 560 to only boot upon the initiation of a VNC connection, simplifying the
 561 installation of operating systems that require immediate keyboard input.
 562 This can be removed for post-installation use.
 563 .It Cm password= Ns Ar password
 564 This type of authentication is known to be cryptographically weak and is not
 565 intended for use on untrusted networks.
 566 Many implementations will want to use stronger security, such as running
 567 the session over an encrypted channel provided by IPsec or SSH.
 568 .El
 569 .Pp
 570 xHCI USB device backends:
 571 .Bl -tag -width 10n
 572 .It Cm tablet
 573 A USB tablet device which provides precise cursor synchronization
 574 when using VNC.
 575 .El
 576 .Pp
 577 NVMe device backends:
 578 .Bl -bullet
 579 .Sm off
 580 .It
 581 .Ar devpath
 582 .Op Cm ,maxq= Ar #
 583 .Op Cm ,qsz= Ar #
 584 .Op Cm ,ioslots= Ar #
 585 .Op Cm ,sectsz= Ar #
 586 .Op Cm ,ser= Ar #
 587 .Op Cm ,eui64= Ar #
 588 .Op Cm ,dsm= Ar opt
 589 .Sm on
 590 .El
 591 .Pp
 592 Configuration options are defined as follows:
 593 .Bl -tag -width 10n
 594 .It Ar devpath
 595 Accepted device paths are:
 596 .Ar /dev/blockdev
 597 or
 598 .Ar /path/to/image
 599 or
 600 .Cm ram= Ns Ar size_in_MiB .
 601 .It Cm maxq
 602 Max number of queues.
 603 .It Cm qsz
 604 Max elements in each queue.
 605 .It Cm ioslots
 606 Max number of concurrent I/O requests.
 607 .It Cm sectsz
 608 Sector size (defaults to blockif sector size).
 609 .It Cm ser
 610 Serial number with maximum 20 characters.
 611 .It Cm eui64
 612 IEEE Extended Unique Identifier (8 byte value).
 613 .It Cm dsm
 614 DataSet Management support.
 615 Supported values are:
 616 .Cm auto , enable ,
 617 and
 618 .Cm disable .
 619 .El
 620 .Pp
 621 AHCI device backends:
 622 .Bl -bullet
 623 .It
 624 .Sm off
 625 .Op Oo Cm hd\&: | cd\&: Oc Ar path
 626 .Op Cm ,nmrr= Ar nmrr
 627 .Op Cm ,ser= Ar #
 628 .Op Cm ,rev= Ar #
 629 .Op Cm ,model= Ar #
 630 .Sm on
 631 .El
 632 .Pp
 633 Configuration options are defined as follows:
 634 .Bl -tag -width 10n
 635 .It Cm nmrr
 636 Nominal Media Rotation Rate, known as RPM.
 637 Value 1 will indicate device as Solid State Disk.
 638 Default value is 0, not report.
 639 .It Cm ser
 640 Serial Number with maximum 20 characters.
 641 .It Cm rev
 642 Revision Number with maximum 8 characters.
 643 .It Cm model
 644 Model Number with maximum 40 characters.
 645 .El
 646 .Pp
 647 HD Audio devices:
 648 .Bl -tag -width 10n
 649 .It Li play
 650 Playback device, typically
 651 .Ar /dev/dsp0 .
 652 .It Li rec
 653 Recording device, typically
 654 .Ar /dev/dsp0 .
 655 .El
 656 .It Fl U Ar uuid
 657 Set the universally unique identifier
 658 .Pq UUID
 659 in the guest's System Management BIOS System Information structure.
 660 By default a UUID is generated from the host's hostname and
 661 .Ar vmname .
 662 .It Fl u
 663 RTC keeps UTC time.
 664 .It Fl W
 665 Force virtio PCI device emulations to use MSI interrupts instead of MSI-X
 666 interrupts.
 667 .It Fl w
 668 Ignore accesses to unimplemented Model Specific Registers (MSRs).
 669 This is intended for debug purposes.
 670 .It Fl x
 671 The guest's local APIC is configured in x2APIC mode.
 672 .It Fl Y
 673 Disable MPtable generation.
 674 .It Ar vmname
 675 Alphanumeric name of the guest.
 676 This should be the same as that created by
 677 .Xr bhyveload 8 .
 678 .El
 679 .Sh DEBUG SERVER
 680 The current debug server provides limited support for debuggers.
 681 .Ss Registers
 682 Each virtual CPU is exposed to the debugger as a thread.
 683 .Pp
 684 General purpose registers can be queried for each virtual CPU, but other
 685 registers such as floating-point and system registers cannot be queried.
 686 .Ss Memory
 687 Memory (including memory mapped I/O regions) can be read by the debugger,
 688 but not written.
 689 Memory operations use virtual addresses that are resolved to physical addresses
 690 via the current virtual CPU's active address translation.
 691 .Ss Control
 692 The running guest can be interrupted by the debugger at any time
 693 .Pq for example, by pressing Ctrl-C in the debugger .
 694 .Pp
 695 Single stepping is only supported on Intel CPUs supporting the MTRAP VM exit.
 696 .Pp
 697 Breakpoints are supported on Intel CPUs that support single stepping.
 698 Note that continuing from a breakpoint while interrupts are enabled in the
 699 guest may not work as expected due to timer interrupts firing while single
 700 stepping over the breakpoint.
 701 .Sh SIGNAL HANDLING
 702 .Nm
 703 deals with the following signals:
 704 .Pp
 705 .Bl -tag -width SIGTERM -compact
 706 .It SIGTERM
 707 Trigger ACPI poweroff for a VM
 708 .El
 709 .Sh EXIT STATUS
 710 Exit status indicates how the VM was terminated:
 711 .Pp
 712 .Bl -tag -width indent -compact
 713 .It 0
 714 rebooted
 715 .It 1
 716 powered off
 717 .It 2
 718 halted
 719 .It 3
 720 triple fault
 721 .It 4
 722 exited due to an error
 723 .El
 724 .Sh EXAMPLES
 725 If not using a boot ROM, the guest operating system must have been loaded with
 726 .Xr bhyveload 8
 727 or a similar boot loader before
 728 .Xr bhyve 4
 729 can be run.
 730 Otherwise, the boot loader is not needed.
 731 .Pp
 732 To run a virtual machine with 1GB of memory, two virtual CPUs, a virtio
 733 block device backed by the
 734 .Pa /my/image
 735 filesystem image, and a serial port for the console:
 736 .Bd -literal -offset indent
 737 bhyve -c 2 -s 0,hostbridge -s 1,lpc -s 2,virtio-blk,/my/image \\
 738   -l com1,stdio -A -H -P -m 1G vm1
 739 .Ed
 740 .Pp
 741 Run a 24GB single-CPU virtual machine with three network ports, one of which
 742 has a MAC address specified:
 743 .Bd -literal -offset indent
 744 bhyve -s 0,hostbridge -s 1,lpc -s 2:0,virtio-net,tap0 \\
 745   -s 2:1,virtio-net,tap1 \\
 746   -s 2:2,virtio-net,tap2,mac=00:be:fa:76:45:00 \\
 747   -s 3,virtio-blk,/my/image -l com1,stdio \\
 748   -A -H -P -m 24G bigvm
 749 .Ed
 750 .Pp
 751 Run an 8GB quad-CPU virtual machine with 8 AHCI SATA disks, an AHCI ATAPI
 752 CD-ROM, a single virtio network port, an AMD hostbridge, and the console
 753 port connected to an
 754 .Xr nmdm 4
 755 null-modem device.
 756 .Bd -literal -offset indent
 757 bhyve -c 4 \\
 758   -s 0,amd_hostbridge -s 1,lpc \\
 759   -s 1:0,ahci,hd:/images/disk.1,hd:/images/disk.2,\\
 760 hd:/images/disk.3,hd:/images/disk.4,\\
 761 hd:/images/disk.5,hd:/images/disk.6,\\
 762 hd:/images/disk.7,hd:/images/disk.8,\\
 763 cd:/images/install.iso \\
 764   -s 3,virtio-net,tap0 \\
 765   -l com1,/dev/nmdm0A \\
 766   -A -H -P -m 8G
 767 .Ed
 768 .Pp
 769 Run a UEFI virtual machine with a display resolution of 800 by 600 pixels
 770 that can be accessed via VNC at: 0.0.0.0:5900.
 771 .Bd -literal -offset indent
 772 bhyve -c 2 -m 4G -w -H \\
 773   -s 0,hostbridge \\
 774   -s 3,ahci-cd,/path/to/uefi-OS-install.iso \\
 775   -s 4,ahci-hd,disk.img \\
 776   -s 5,virtio-net,tap0 \\
 777   -s 29,fbuf,tcp=0.0.0.0:5900,w=800,h=600,wait \\
 778   -s 30,xhci,tablet \\
 779   -s 31,lpc -l com1,stdio \\
 780   -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \\
 781    uefivm
 782 .Ed
 783 .Pp
 784 Run a UEFI virtual machine with a VNC display that is bound to all IPv6
 785 addresses on port 5900.
 786 .Bd -literal -offset indent
 787 bhyve -c 2 -m 4G -w -H \\
 788   -s 0,hostbridge \\
 789   -s 4,ahci-hd,disk.img \\
 790   -s 5,virtio-net,tap0 \\
 791   -s 29,fbuf,tcp=[::]:5900,w=800,h=600 \\
 792   -s 30,xhci,tablet \\
 793   -s 31,lpc -l com1,stdio \\
 794   -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \\
 795    uefivm
 796 .Ed
 797 .Sh SEE ALSO
 798 .Xr bhyve 4 ,
 799 .Xr nmdm 4 ,
 800 .Xr vmm 4 ,
 801 .Xr ethers 5 ,
 802 .Xr bhyvectl 8 ,
 803 .Xr bhyveload 8
 804 .Pp
 805 .Rs
 806 .%A Intel
 807 .%B 64 and IA-32 Architectures Software Developer’s Manual
 808 .%V Volume 3
 809 .Re
 810 .Sh HISTORY
 811 .Nm
 812 first appeared in
 813 .Fx 10.0 .
 814 .Sh AUTHORS
 815 .An Neel Natu Aq Mt neel@freebsd.org
 816 .An Peter Grehan Aq Mt grehan@freebsd.org