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 July 9, 2016 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 abehuwxACHPSWY 36.Op Fl c Ar numcpus 37.Op Fl g Ar gdbport 38.Op Fl l Ar lpcdev Ns Op , Ns Ar conf 39.Op Fl m Ar memsize Ns Op Ar K|k|M|m|G|g|T|t 40.Op Fl p Ar vcpu:hostcpu 41.Op Fl s Ar slot,emulation Ns Op , Ns Ar conf 42.Op Fl U Ar uuid 43.Ar vmname 44.Sh DESCRIPTION 45.Nm 46is a hypervisor that runs guest operating systems inside a 47virtual machine. 48.Pp 49Parameters such as the number of virtual CPUs, amount of guest memory, and 50I/O connectivity can be specified with command-line parameters. 51.Pp 52The guest operating system must be loaded with 53.Xr bhyveload 8 54or a similar boot loader before running 55.Nm . 56.Pp 57.Nm 58runs until the guest operating system reboots or an unhandled hypervisor 59exit is detected. 60.Sh OPTIONS 61.Bl -tag -width 10n 62.It Fl a 63The guest's local APIC is configured in xAPIC mode. 64The xAPIC mode is the default setting so this option is redundant. 65It will be deprecated in a future version. 66.It Fl A 67Generate ACPI tables. 68Required for 69.Fx Ns /amd64 70guests. 71.It Fl b 72Enable a low-level console device supported by 73.Fx 74kernels compiled with 75.Cd "device bvmconsole" . 76This option will be deprecated in a future version. 77.It Fl c Ar numcpus 78Number of guest virtual CPUs. 79The default is 1 and the maximum is 16. 80.It Fl C 81Include guest memory in core file. 82.It Fl e 83Force 84.Nm 85to exit when a guest issues an access to an I/O port that is not emulated. 86This is intended for debug purposes. 87.It Fl g Ar gdbport 88For 89.Fx 90kernels compiled with 91.Cd "device bvmdebug" , 92allow a remote kernel kgdb to be relayed to the guest kernel gdb stub 93via a local IPv4 address and this port. 94This option will be deprecated in a future version. 95.It Fl h 96Print help message and exit. 97.It Fl H 98Yield the virtual CPU thread when a HLT instruction is detected. 99If this option is not specified, virtual CPUs will use 100% of a host CPU. 100.It Fl l Ar lpcdev Ns Op , Ns Ar conf 101Allow devices behind the LPC PCI-ISA bridge to be configured. 102The only supported devices are the TTY-class devices 103.Ar com1 104and 105.Ar com2 106and the boot ROM device 107.Ar bootrom . 108.It Fl m Ar memsize Ns Op Ar K|k|M|m|G|g|T|t 109Guest physical memory size in bytes. 110This must be the same size that was given to 111.Xr bhyveload 8 . 112.Pp 113The size argument may be suffixed with one of K, M, G or T (either upper 114or lower case) to indicate a multiple of kilobytes, megabytes, gigabytes, 115or terabytes. 116If no suffix is given, the value is assumed to be in megabytes. 117.Pp 118.Ar memsize 119defaults to 256M. 120.It Fl p Ar vcpu:hostcpu 121Pin guest's virtual CPU 122.Em vcpu 123to 124.Em hostcpu . 125.It Fl P 126Force the guest virtual CPU to exit when a PAUSE instruction is detected. 127.It Fl s Ar slot,emulation Ns Op , Ns Ar conf 128Configure a virtual PCI slot and function. 129.Pp 130.Nm 131provides PCI bus emulation and virtual devices that can be attached to 132slots on the bus. 133There are 32 available slots, with the option of providing up to 8 functions 134per slot. 135.Bl -tag -width 10n 136.It Ar slot 137.Ar pcislot[:function] 138.Ar bus:pcislot:function 139.Pp 140The 141.Ar pcislot 142value is 0 to 31. 143The optional 144.Ar function 145value is 0 to 7. 146The optional 147.Ar bus 148value is 0 to 255. 149If not specified, the 150.Ar function 151value defaults to 0. 152If not specified, the 153.Ar bus 154value defaults to 0. 155.It Ar emulation 156.Bl -tag -width 10n 157.It Li hostbridge | Li amd_hostbridge 158.Pp 159Provide a simple host bridge. 160This is usually configured at slot 0, and is required by most guest 161operating systems. 162The 163.Li amd_hostbridge 164emulation is identical but uses a PCI vendor ID of 165.Li AMD . 166.It Li passthru 167PCI pass-through device. 168.It Li virtio-net 169Virtio network interface. 170.It Li virtio-blk 171Virtio block storage interface. 172.It Li virtio-rnd 173Virtio RNG interface. 174.It Li ahci 175AHCI controller attached to arbitraty devices. 176.It Li ahci-cd 177AHCI controller attached to an ATAPI CD/DVD. 178.It Li ahci-hd 179AHCI controller attached to a SATA hard-drive. 180.It Li e1000 181Intel e82545 network interface. 182.It Li uart 183PCI 16550 serial device. 184.It Li lpc 185LPC PCI-ISA bridge with COM1 and COM2 16550 serial ports and a boot ROM. 186The LPC bridge emulation can only be configured on bus 0. 187.El 188.It Op Ar conf 189This optional parameter describes the backend for device emulations. 190If 191.Ar conf 192is not specified, the device emulation has no backend and can be 193considered unconnected. 194.Pp 195Network devices: 196.Bl -tag -width 10n 197.It Ar tapN Ns Op , Ns Ar mac=xx:xx:xx:xx:xx:xx 198.It Ar vmnetN Ns Op , Ns Ar mac=xx:xx:xx:xx:xx:xx 199.Pp 200If 201.Ar mac 202is not specified, the MAC address is derived from a fixed OUI and the 203remaining bytes from an MD5 hash of the slot and function numbers and 204the device name. 205.Pp 206The MAC address is an ASCII string in 207.Xr ethers 5 208format. 209.El 210.Pp 211Block storage devices: 212.Bl -tag -width 10n 213.It Pa /filename Ns Oo , Ns Ar block-device-options Oc 214.It Pa /dev/xxx Ns Oo , Ns Ar block-device-options Oc 215.El 216.Pp 217The 218.Ar block-device-options 219are: 220.Bl -tag -width 8n 221.It Li nocache 222Open the file with 223.Dv O_DIRECT . 224.It Li direct 225Open the file using 226.Dv O_SYNC . 227.It Li ro 228Force the file to be opened read-only. 229.It Li sectorsize= Ns Ar logical Ns Oo / Ns Ar physical Oc 230Specify the logical and physical sector sizes of the emulated disk. 231The physical sector size is optional and is equal to the logical sector size 232if not explicitly specified. 233.El 234.Pp 235TTY devices: 236.Bl -tag -width 10n 237.It Li stdio 238Connect the serial port to the standard input and output of 239the 240.Nm 241process. 242.It Pa /dev/xxx 243Use the host TTY device for serial port I/O. 244.El 245.Pp 246Boot ROM device: 247.Bl -tag -width 10n 248.It Pa romfile 249Map 250.Ar romfile 251in the guest address space reserved for boot firmware. 252.El 253.Pp 254Pass-through devices: 255.Bl -tag -width 10n 256.It Ns Ar slot Ns / Ns Ar bus Ns / Ns Ar function 257Connect to a PCI device on the host at the selector described by 258.Ar slot , 259.Ar bus , 260and 261.Ar function 262numbers. 263.El 264.Pp 265Guest memory must be wired using the 266.Fl S 267option when a pass-through device is configured. 268.Pp 269The host device must have been reserved at boot-time using the 270.Va pptdev 271loader variable as described in 272.Xr vmm 4 . 273.El 274.It Fl S 275Wire guest memory. 276.It Fl u 277RTC keeps UTC time. 278.It Fl U Ar uuid 279Set the universally unique identifier 280.Pq UUID 281in the guest's System Management BIOS System Information structure. 282By default a UUID is generated from the host's hostname and 283.Ar vmname . 284.It Fl w 285Ignore accesses to unimplemented Model Specific Registers (MSRs). 286This is intended for debug purposes. 287.It Fl W 288Force virtio PCI device emulations to use MSI interrupts instead of MSI-X 289interrupts. 290.It Fl x 291The guest's local APIC is configured in x2APIC mode. 292.It Fl Y 293Disable MPtable generation. 294.It Ar vmname 295Alphanumeric name of the guest. 296This should be the same as that created by 297.Xr bhyveload 8 . 298.El 299.Sh SIGNAL HANDLING 300.Nm 301deals with the following signals: 302.Pp 303.Bl -tag -width indent -compact 304.It SIGTERM 305Trigger ACPI poweroff for a VM 306.El 307.Sh EXIT STATUS 308Exit status indicates how the VM was terminated: 309.Pp 310.Bl -tag -width indent -compact 311.It 0 312rebooted 313.It 1 314powered off 315.It 2 316halted 317.It 3 318triple fault 319.El 320.Sh EXAMPLES 321The guest operating system must have been loaded with 322.Xr bhyveload 8 323or a similar boot loader before 324.Xr bhyve 4 325can be run. 326.Pp 327To run a virtual machine with 1GB of memory, two virtual CPUs, a virtio 328block device backed by the 329.Pa /my/image 330filesystem image, and a serial port for the console: 331.Bd -literal -offset indent 332bhyve -c 2 -s 0,hostbridge -s 1,lpc -s 2,virtio-blk,/my/image \\ 333 -l com1,stdio -A -H -P -m 1G vm1 334.Ed 335.Pp 336Run a 24GB single-CPU virtual machine with three network ports, one of which 337has a MAC address specified: 338.Bd -literal -offset indent 339bhyve -s 0,hostbridge -s 1,lpc -s 2:0,virtio-net,tap0 \\ 340 -s 2:1,virtio-net,tap1 \\ 341 -s 2:2,virtio-net,tap2,mac=00:be:fa:76:45:00 \\ 342 -s 3,virtio-blk,/my/image -l com1,stdio \\ 343 -A -H -P -m 24G bigvm 344.Ed 345.Pp 346Run an 8GB quad-CPU virtual machine with 8 AHCI SATA disks, an AHCI ATAPI 347CD-ROM, a single virtio network port, an AMD hostbridge, and the console 348port connected to an 349.Xr nmdm 4 350null-modem device. 351.Bd -literal -offset indent 352bhyve -c 4 \\ 353 -s 0,amd_hostbridge -s 1,lpc \\ 354 -s 1:0,ahci,hd:/images/disk.1,hd:/images/disk.2,\\ 355hd:/images/disk.3,hd:/images/disk.4,\\ 356hd:/images/disk.5,hd:/images/disk.6,\\ 357hd:/images/disk.7,hd:/images/disk.8,\\ 358cd:/images/install.iso \\ 359 -s 3,virtio-net,tap0 \\ 360 -l com1,/dev/nmdm0A \\ 361 -A -H -P -m 8G 362.Ed 363.Sh SEE ALSO 364.Xr bhyve 4 , 365.Xr nmdm 4 , 366.Xr vmm 4 , 367.Xr ethers 5 , 368.Xr bhyvectl 8 , 369.Xr bhyveload 8 370.Sh HISTORY 371.Nm 372first appeared in 373.Fx 10.0 . 374.Sh AUTHORS 375.An Neel Natu Aq Mt neel@freebsd.org 376.An Peter Grehan Aq Mt grehan@freebsd.org 377