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