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 December 12, 2013 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 aehwAHPW 36.Op Fl c Ar numcpus 37.Op Fl g Ar gdbport 38.Op Fl p Ar pinnedcpu 39.Op Fl s Ar slot,emulation Ns Op , Ns Ar conf 40.Op Fl S Ar slot,emulation Ns Op , Ns Ar conf 41.Op Fl l Ar lpcdev Ns Op , Ns Ar conf 42.Ar vmname 43.Sh DESCRIPTION 44.Nm 45is an experimental hypervisor that runs guest operating systems inside a 46virtual machine. 47.Pp 48Parameters such as the number of virtual CPUs, amount of guest memory, and 49I/O connectivity can be specified with command-line parameters. 50.Pp 51The guest operating system must be loaded with 52.Xr bhyveload 4 53or a similar boot loader before running 54.Nm . 55.Pp 56.Nm 57runs until the guest operating system reboots or an unhandled hypervisor 58exit is detected. 59.Sh OPTIONS 60.Bl -tag -width 10n 61.It Fl a 62Disallow use of the local APIC in X2APIC mode. 63.It Fl A 64Generate ACPI tables. 65Required for 66.Fx Ns /amd64 67guests. 68.It Fl c Ar numcpus 69Number of guest virtual CPUs. 70The default is 1 and the maximum is 16. 71.It Fl H 72Yield the virtual CPU thread when a HLT instruction is detected. 73If this option is not specified, virtual CPUs will use 100% of a host CPU. 74.It Fl g Ar gdbport 75For 76.Fx Ns /amd64 kernels compiled with 77.Cd "option bvmdebug" , 78allow a remote kernel kgdb to be relayed to the guest kernel gdb stub 79via a local IPv4 address and this port. 80This option will be deprecated in a future version. 81.It Fl p Ar pinnedcpu 82Force guest virtual CPUs to be pinned to host CPUs. 83Virtual CPU 84.Em n 85is pinned to host CPU 86.Em pinnedcpu+n . 87.It Fl P 88Force the guest virtual CPU to exit when a PAUSE instruction is detected. 89.It Fl W 90Force virtio PCI device emulations to use MSI interrupts instead of MSI-X 91interrupts. 92.It Fl s Ar slot,emulation Ns Op , Ns Ar conf 93Configure a virtual PCI slot and function. 94.Pp 95.Nm bhyve 96provides PCI bus emulation and virtual devices that can be attached to 97slots on the bus. 98There are 32 available slots, with the option of providing up to 8 functions 99per slot. 100.Bl -tag -width 10n 101.It Ar slot 102.Ar pcislot Ns Op Ar :function 103.Pp 104The 105.Ar pcislot 106value is 0 to 31 and the optional function value is 0 to 7. 107If not specified, the function value defaults to 0. 108.It Ar emulation 109.Bl -tag -width 10n 110.It Li hostbridge | Li amd_hostbridge 111.Pp 112Provide a simple host bridge. 113This is usually configured at slot 0, and is required by most guest 114operating systems. 115The 116.Li amd_hostbridge 117emulation is identical but uses a PCI vendor ID of 118.Li AMD . 119.It Li passthru 120PCI pass-through device. 121.It Li virtio-net 122Virtio network interface. 123.It Li virtio-blk 124Virtio block storage interface. 125.It Li ahci-cd 126AHCI controller attached to an ATAPI CD/DVD. 127.It Li ahci-hd 128AHCI controller attached to a SATA hard-drive. 129.It Li uart 130PCI 16550 serial device. 131.It Li lpc 132LPC PCI-ISA bridge with COM1 and COM2 16550 serial ports. 133.El 134.It Op Ar conf 135This optional parameter describes the backend for device emulations. 136If 137.Ar conf 138is not specified, the device emulation has no backend and can be 139considered unconnected. 140.Pp 141Network devices: 142.Bl -tag -width 10n 143.It Ar tapN Ns Op , Ns Ar mac=xx:xx:xx:xx:xx:xx 144.It Ar vmnetN Ns Op , Ns Ar mac=xx:xx:xx:xx:xx:xx 145.Pp 146If 147.Ar mac 148is not specified, the MAC address is derived from a fixed OUI and the 149remaining bytes from an MD5 hash of the slot and function numbers and 150the device name. 151.Pp 152The MAC address is an ASCII string in 153.Xr ethers 5 154format. 155.El 156.Pp 157Block storage devices: 158.Bl -tag -width 10n 159.It Pa /filename Ns Oo , Ns Li nocache Oc Ns Oo , Ns Li direct Oc Ns Oo , Ns Li ro Oc 160.It Pa /dev/xxx Ns Oo , Ns Ar nocache Oc Ns Oo , Ns Ar direct Oc Ns Oo , Ns Ar ro Oc 161.Bl -tag -width 8n 162.It Li nocache 163Open the file with 164.Dv O_DIRECT . 165.It Li direct 166Open the file using 167.Dv O_SYNC . 168.It Li ro 169Force the file to be opened read-only. 170.El 171.Pp 172The 173.Li nocache , 174.Li direct , 175and 176.Li ro 177options are not available for virtio block devices. 178.El 179.Pp 180TTY devices: 181.Bl -tag -width 10n 182.It Li stdio 183Connect the serial port to the standard input and output of 184the bhyve process. 185.It Pa /dev/xxx 186Use the host TTY device for serial port I/O. 187.El 188.Pp 189Pass-through devices: 190.Bl -tag -width 10n 191.It Ns Ar slot Ns / Ns Ar bus Ns / Ns Ar function 192Connect to a PCI device on the host at the selector described by 193.Ar slot , 194.Ar bus , 195and 196.Ar function 197numbers. 198.El 199.Pp 200The host device must have been reserved at boot-time using the 201.Va pptdev 202loader variable as described in 203.Xr vmm 4 . 204.El 205.It Fl S Ar slot , Ns Ar emulation Ns Op , Ns Ar conf 206Identical to the -s option except the device is instructed to use legacy 207ISA addresses if possible. 208Currently this only has an effect with the 209.Li uart 210device emulation. 211This option will be deprecated in a future version. 212.It Fl l Ar lpcdev Ns Op , Ns Ar conf 213Allow devices behind the LPC PCI-ISA bridge to be configured. 214The only supported devices are the TTY-class devices, 215.Li com1 216and 217.Li com2 . 218.It Fl m Ar size Ns Op Ar K|k|M|m|G|g|T|t 219Guest physical memory size in bytes. 220This must be the same size that was given to 221.Xr bhyveload 8 . 222.Pp 223The size argument may be suffixed with one of K, M, G or T (either upper 224or lower case) to indicate a multiple of kilobytes, megabytes, gigabytes, 225or terabytes. 226If no suffix is given, the value is assumed to be in megabytes. 227.It Fl e 228Force 229.Nm 230to exit when a guest issues an access to an I/O port that is not emulated. 231This is intended for debug purposes. 232.It Fl w 233Ignore accesses to unimplemented Model Specific Registers (MSRs). This is intended for debug purposes. 234.It Fl h 235Print help message and exit. 236.It Ar vmname 237Alphanumeric name of the guest. 238This should be the same as that created by 239.Xr bhyveload 8 . 240.El 241.Sh EXAMPLES 242The guest operating system must have been loaded with 243.Xr bhyveload 4 244or a similar boot loader before 245.Xr bhyve 4 246can be run. 247.Pp 248To run a virtual machine with 1GB of memory, two virtual CPUs, a virtio 249block device backed by the 250.Pa /my/image 251filesystem image, and a serial port for the console: 252.Bd -literal -offset indent 253bhyve -c 2 -s 0,hostbridge -s 1,lpc -s 2,virtio-blk,/my/image \\ 254 -l com1,stdio -A -H -P -m 1G vm1 255.Ed 256.Pp 257Run a 24GB single-CPU virtual machine with three network ports, one of which 258has a MAC address specified: 259.Bd -literal -offset indent 260bhyve -s 0,hostbridge -s 1,lpc -s 2:0,virtio-net,tap0 \\ 261 -s 2:1,virtio-net,tap1 \\ 262 -s 2:2,virtio-net,tap2,mac=00:be:fa:76:45:00 \\ 263 -s 3,virtio-blk,/my/image -l com1,stdio \\ 264 -A -H -P -m 24G bigvm 265.Ed 266.Pp 267Run an 8GB quad-CPU virtual machine with 8 AHCI SATA disks, an AHCI ATAPI 268CD-ROM, a single virtio network port, an AMD hostbridge, and the console 269port connected to an 270.Xr nmdm 4 271null-model device. 272.Bd -literal -offset indent 273bhyve -c 4 \e\ 274 -s 0,amd_hostbridge -s 1,lpc \\ 275 -s 1:0,ahci-hd,/images/disk.1 \\ 276 -s 1:1,ahci-hd,/images/disk.2 \\ 277 -s 1:2,ahci-hd,/images/disk.3 \\ 278 -s 1:3,ahci-hd,/images/disk.4 \\ 279 -s 1:4,ahci-hd,/images/disk.5 \\ 280 -s 1:5,ahci-hd,/images/disk.6 \\ 281 -s 1:6,ahci-hd,/images/disk.7 \\ 282 -s 1:7,ahci-hd,/images/disk.8 \\ 283 -s 2,ahci-cd,/images.install.iso \\ 284 -s 3,virtio-net,tap0 \\ 285 -l com1,/dev/nmdm0A \\ 286 -A -H -P -m 8G 287.Ed 288.Sh SEE ALSO 289.Xr bhyve 4 , 290.Xr nmdm 4 , 291.Xr vmm 4 , 292.Xr ethers 5 , 293.Xr bhyvectl 8 , 294.Xr bhyveload 8 295.Sh HISTORY 296.Nm 297first appeared in 298.Fx 10.0 . 299.Sh AUTHORS 300.An Neel Natu Aq neel@freebsd.org 301.An Peter Grehan Aq grehan@freebsd.org 302