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