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