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