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 September 17, 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 abehwxACHPWY 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 size 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 4 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. It will be 65deprecated 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.Li com1 104and 105.Li com2 . 106.It Fl m Ar size Ns Op Ar K|k|M|m|G|g|T|t 107Guest physical memory size in bytes. 108This must be the same size that was given to 109.Xr bhyveload 8 . 110.Pp 111The size argument may be suffixed with one of K, M, G or T (either upper 112or lower case) to indicate a multiple of kilobytes, megabytes, gigabytes, 113or terabytes. 114If no suffix is given, the value is assumed to be in megabytes. 115.It Fl p Ar vcpu:hostcpu 116Pin guest's virtual CPU 117.Em vcpu 118to 119.Em hostcpu . 120.It Fl P 121Force the guest virtual CPU to exit when a PAUSE instruction is detected. 122.It Fl s Ar slot,emulation Ns Op , Ns Ar conf 123Configure a virtual PCI slot and function. 124.Pp 125.Nm bhyve 126provides PCI bus emulation and virtual devices that can be attached to 127slots on the bus. 128There are 32 available slots, with the option of providing up to 8 functions 129per slot. 130.Bl -tag -width 10n 131.It Ar slot 132.Ar pcislot[:function] 133.Ar bus:pcislot:function 134.Pp 135The 136.Ar pcislot 137value is 0 to 31. The optional function value is 0 to 7. The optional 138.Ar bus 139value is 0 to 255. 140If not specified, the function value defaults to 0. 141If not specified, the bus value defaults to 0. 142.It Ar emulation 143.Bl -tag -width 10n 144.It Li hostbridge | Li amd_hostbridge 145.Pp 146Provide a simple host bridge. 147This is usually configured at slot 0, and is required by most guest 148operating systems. 149The 150.Li amd_hostbridge 151emulation is identical but uses a PCI vendor ID of 152.Li AMD . 153.It Li passthru 154PCI pass-through device. 155.It Li virtio-net 156Virtio network interface. 157.It Li virtio-blk 158Virtio block storage interface. 159.It Li virtio-rnd 160Virtio RNG interface. 161.It Li ahci-cd 162AHCI controller attached to an ATAPI CD/DVD. 163.It Li ahci-hd 164AHCI controller attached to a SATA hard-drive. 165.It Li uart 166PCI 16550 serial device. 167.It Li lpc 168LPC PCI-ISA bridge with COM1 and COM2 16550 serial ports. The LPC bridge 169emulation can only be configured on bus 0. 170.El 171.It Op Ar conf 172This optional parameter describes the backend for device emulations. 173If 174.Ar conf 175is not specified, the device emulation has no backend and can be 176considered unconnected. 177.Pp 178Network devices: 179.Bl -tag -width 10n 180.It Ar tapN Ns Op , Ns Ar mac=xx:xx:xx:xx:xx:xx 181.It Ar vmnetN Ns Op , Ns Ar mac=xx:xx:xx:xx:xx:xx 182.Pp 183If 184.Ar mac 185is not specified, the MAC address is derived from a fixed OUI and the 186remaining bytes from an MD5 hash of the slot and function numbers and 187the device name. 188.Pp 189The MAC address is an ASCII string in 190.Xr ethers 5 191format. 192.El 193.Pp 194Block storage devices: 195.Bl -tag -width 10n 196.It Pa /filename Ns Oo , Ns Li nocache Oc Ns Oo , Ns Li direct Oc Ns Oo , Ns Li ro Oc 197.It Pa /dev/xxx Ns Oo , Ns Ar nocache Oc Ns Oo , Ns Ar direct Oc Ns Oo , Ns Ar ro Oc 198.Bl -tag -width 8n 199.It Li nocache 200Open the file with 201.Dv O_DIRECT . 202.It Li direct 203Open the file using 204.Dv O_SYNC . 205.It Li ro 206Force the file to be opened read-only. 207.El 208.Pp 209The 210.Li nocache , 211.Li direct , 212and 213.Li ro 214options are not available for virtio block devices. 215.El 216.Pp 217TTY devices: 218.Bl -tag -width 10n 219.It Li stdio 220Connect the serial port to the standard input and output of 221the bhyve process. 222.It Pa /dev/xxx 223Use the host TTY device for serial port I/O. 224.El 225.Pp 226Pass-through devices: 227.Bl -tag -width 10n 228.It Ns Ar slot Ns / Ns Ar bus Ns / Ns Ar function 229Connect to a PCI device on the host at the selector described by 230.Ar slot , 231.Ar bus , 232and 233.Ar function 234numbers. 235.El 236.Pp 237The host device must have been reserved at boot-time using the 238.Va pptdev 239loader variable as described in 240.Xr vmm 4 . 241.El 242.It Fl U Ar uuid 243Set the universally unique identifier 244.Pq UUID 245in the guest's System Management BIOS System Information structure. 246By default a UUID is generated from the host's hostname and 247.Ar vmname . 248.It Fl w 249Ignore accesses to unimplemented Model Specific Registers (MSRs). This is intended for debug purposes. 250.It Fl W 251Force virtio PCI device emulations to use MSI interrupts instead of MSI-X 252interrupts. 253.It Fl x 254The guest's local APIC is configured in x2APIC mode. 255.It Fl Y 256Disable MPtable generation. 257.It Ar vmname 258Alphanumeric name of the guest. 259This should be the same as that created by 260.Xr bhyveload 8 . 261.El 262.Sh EXAMPLES 263The guest operating system must have been loaded with 264.Xr bhyveload 4 265or a similar boot loader before 266.Xr bhyve 4 267can be run. 268.Pp 269To run a virtual machine with 1GB of memory, two virtual CPUs, a virtio 270block device backed by the 271.Pa /my/image 272filesystem image, and a serial port for the console: 273.Bd -literal -offset indent 274bhyve -c 2 -s 0,hostbridge -s 1,lpc -s 2,virtio-blk,/my/image \\ 275 -l com1,stdio -A -H -P -m 1G vm1 276.Ed 277.Pp 278Run a 24GB single-CPU virtual machine with three network ports, one of which 279has a MAC address specified: 280.Bd -literal -offset indent 281bhyve -s 0,hostbridge -s 1,lpc -s 2:0,virtio-net,tap0 \\ 282 -s 2:1,virtio-net,tap1 \\ 283 -s 2:2,virtio-net,tap2,mac=00:be:fa:76:45:00 \\ 284 -s 3,virtio-blk,/my/image -l com1,stdio \\ 285 -A -H -P -m 24G bigvm 286.Ed 287.Pp 288Run an 8GB quad-CPU virtual machine with 8 AHCI SATA disks, an AHCI ATAPI 289CD-ROM, a single virtio network port, an AMD hostbridge, and the console 290port connected to an 291.Xr nmdm 4 292null-model device. 293.Bd -literal -offset indent 294bhyve -c 4 \e\ 295 -s 0,amd_hostbridge -s 1,lpc \\ 296 -s 1:0,ahci-hd,/images/disk.1 \\ 297 -s 1:1,ahci-hd,/images/disk.2 \\ 298 -s 1:2,ahci-hd,/images/disk.3 \\ 299 -s 1:3,ahci-hd,/images/disk.4 \\ 300 -s 1:4,ahci-hd,/images/disk.5 \\ 301 -s 1:5,ahci-hd,/images/disk.6 \\ 302 -s 1:6,ahci-hd,/images/disk.7 \\ 303 -s 1:7,ahci-hd,/images/disk.8 \\ 304 -s 2,ahci-cd,/images.install.iso \\ 305 -s 3,virtio-net,tap0 \\ 306 -l com1,/dev/nmdm0A \\ 307 -A -H -P -m 8G 308.Ed 309.Sh SEE ALSO 310.Xr bhyve 4 , 311.Xr nmdm 4 , 312.Xr vmm 4 , 313.Xr ethers 5 , 314.Xr bhyvectl 8 , 315.Xr bhyveload 8 316.Sh HISTORY 317.Nm 318first appeared in 319.Fx 10.0 . 320.Sh AUTHORS 321.An Neel Natu Aq Mt neel@freebsd.org 322.An Peter Grehan Aq Mt grehan@freebsd.org 323