usr.sbin/bhyve/bhyve.8

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