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