Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
BHYVE(8)                FreeBSD System Manager's Manual               BHYVE(8)

NAME
     bhyve - run a guest operating system inside a virtual machine

SYNOPSIS
     bhyve [-abehuwxACHPSWY] [-c numcpus] [-g gdbport] [-l lpcdev[,conf]]
           [-m size[K|k|M|m|G|g|T|t]] [-p vcpu:hostcpu]
           [-s slot,emulation[,conf]] [-U uuid] vmname

DESCRIPTION
     bhyve is a hypervisor that runs guest operating systems inside a virtual
     machine.

     Parameters such as the number of virtual CPUs, amount of guest memory,
     and I/O connectivity can be specified with command-line parameters.

     The guest operating system must be loaded with bhyveload(8) or a similar
     boot loader before running bhyve.

     bhyve runs until the guest operating system reboots or an unhandled
     hypervisor exit is detected.

OPTIONS
     -a          The guest's local APIC is configured in xAPIC mode.  The
                 xAPIC mode is the default setting so this option is
                 redundant.  It will be deprecated in a future version.

     -A          Generate ACPI tables.  Required for FreeBSD/amd64 guests.

     -b          Enable a low-level console device supported by FreeBSD
                 kernels compiled with device bvmconsole.  This option will be
                 deprecated in a future version.

     -c numcpus  Number of guest virtual CPUs.  The default is 1 and the
                 maximum is 16.

     -C          Include guest memory in core file.

     -e          Force bhyve to exit when a guest issues an access to an I/O
                 port that is not emulated.  This is intended for debug
                 purposes.

     -g gdbport  For FreeBSD kernels compiled with device bvmdebug, allow a
                 remote kernel kgdb to be relayed to the guest kernel gdb stub
                 via a local IPv4 address and this port.  This option will be
                 deprecated in a future version.

     -h          Print help message and exit.

     -H          Yield the virtual CPU thread when a HLT instruction is
                 detected.  If this option is not specified, virtual CPUs will
                 use 100% of a host CPU.

     -l lpcdev[,conf]
                 Allow devices behind the LPC PCI-ISA bridge to be configured.
                 The only supported devices are the TTY-class devices com1 and
                 com2 and the boot ROM device bootrom.

     -m size[K|k|M|m|G|g|T|t]
                 Guest physical memory size in bytes.  This must be the same
                 size that was given to bhyveload(8).

                 The size argument may be suffixed with one of K, M, G or T
                 (either upper or lower case) to indicate a multiple of
                 kilobytes, megabytes, gigabytes, or terabytes.  If no suffix
                 is given, the value is assumed to be in megabytes.

     -p vcpu:hostcpu
                 Pin guest's virtual CPU vcpu to hostcpu.

     -P          Force the guest virtual CPU to exit when a PAUSE instruction
                 is detected.

     -s slot,emulation[,conf]
                 Configure a virtual PCI slot and function.

                 bhyve provides PCI bus emulation and virtual devices that can
                 be attached to slots on the bus.  There are 32 available
                 slots, with the option of providing up to 8 functions per
                 slot.

                 slot        pcislot[:function] bus:pcislot:function

                             The pcislot value is 0 to 31.  The optional
                             function value is 0 to 7.  The optional bus value
                             is 0 to 255.  If not specified, the function
                             value defaults to 0.  If not specified, the bus
                             value defaults to 0.

                 emulation

                             hostbridge | amd_hostbridge

                                         Provide a simple host bridge.  This
                                         is usually configured at slot 0, and
                                         is required by most guest operating
                                         systems.  The amd_hostbridge
                                         emulation is identical but uses a PCI
                                         vendor ID of AMD.

                             passthru    PCI pass-through device.

                             virtio-net  Virtio network interface.

                             virtio-blk  Virtio block storage interface.

                             virtio-rnd  Virtio RNG interface.

                             ahci-cd     AHCI controller attached to an ATAPI
                                         CD/DVD.

                             ahci-hd     AHCI controller attached to a SATA
                                         hard-drive.

                             uart        PCI 16550 serial device.

                             lpc         LPC PCI-ISA bridge with COM1 and COM2
                                         16550 serial ports and a boot ROM.
                                         The LPC bridge emulation can only be
                                         configured on bus 0.

                 [conf]      This optional parameter describes the backend for
                             device emulations.  If conf is not specified, the
                             device emulation has no backend and can be
                             considered unconnected.

                             Network devices:

                             tapN[,mac=xx:xx:xx:xx:xx:xx]

                             vmnetN[,mac=xx:xx:xx:xx:xx:xx]

                                         If mac is not specified, the MAC
                                         address is derived from a fixed OUI
                                         and the remaining bytes from an MD5
                                         hash of the slot and function numbers
                                         and the device name.

                                         The MAC address is an ASCII string in
                                         ethers(5) format.

                             Block storage devices:

                             /filename[,block-device-options]

                             /dev/xxx[,block-device-options]

                             The block-device-options are:

                             nocache   Open the file with O_DIRECT.

                             direct    Open the file using O_SYNC.

                             ro        Force the file to be opened read-only.

                             sectorsize=logical[/physical]
                                       Specify the logical and physical sector
                                       sizes of the emulated disk.  The
                                       physical sector size is optional and is
                                       equal to the logical sector size if not
                                       explicitly specified.

                             TTY devices:

                             stdio       Connect the serial port to the
                                         standard input and output of the
                                         bhyve process.

                             /dev/xxx    Use the host TTY device for serial
                                         port I/O.

                             Boot ROM device:

                             romfile     Map romfile in the guest address
                                         space reserved for boot firmware.

                             Pass-through devices:

                             slot/bus/function
                                         Connect to a PCI device on the host
                                         at the selector described by slot,
                                         bus, and function numbers.

                             Guest memory must be wired using the -S option
                             when a pass-through device is configured.

                             The host device must have been reserved at boot-
                             time using the pptdev loader variable as
                             described in vmm(4).

     -S          Wire guest memory.

     -u          RTC keeps UTC time.

     -U uuid     Set the universally unique identifier (UUID) in the guest's
                 System Management BIOS System Information structure.  By
                 default a UUID is generated from the host's hostname and
                 vmname.

     -w          Ignore accesses to unimplemented Model Specific Registers
                 (MSRs).  This is intended for debug purposes.

     -W          Force virtio PCI device emulations to use MSI interrupts
                 instead of MSI-X interrupts.

     -x          The guest's local APIC is configured in x2APIC mode.

     -Y          Disable MPtable generation.

     vmname      Alphanumeric name of the guest.  This should be the same as
                 that created by bhyveload(8).

EXAMPLES
     The guest operating system must have been loaded with bhyveload(8) or a
     similar boot loader before bhyve(4) can be run.

     To run a virtual machine with 1GB of memory, two virtual CPUs, a virtio
     block device backed by the /my/image filesystem image, and a serial port
     for the console:

           bhyve -c 2 -s 0,hostbridge -s 1,lpc -s 2,virtio-blk,/my/image \
             -l com1,stdio -A -H -P -m 1G vm1

     Run a 24GB single-CPU virtual machine with three network ports, one of
     which has a MAC address specified:

           bhyve -s 0,hostbridge -s 1,lpc -s 2:0,virtio-net,tap0 \
             -s 2:1,virtio-net,tap1 \
             -s 2:2,virtio-net,tap2,mac=00:be:fa:76:45:00 \
             -s 3,virtio-blk,/my/image -l com1,stdio \
             -A -H -P -m 24G bigvm

     Run an 8GB quad-CPU virtual machine with 8 AHCI SATA disks, an AHCI ATAPI
     CD-ROM, a single virtio network port, an AMD hostbridge, and the console
     port connected to an nmdm(4) null-modem device.

           bhyve -c 4 \
             -s 0,amd_hostbridge -s 1,lpc \
             -s 1:0,ahci-hd,/images/disk.1 \
             -s 1:1,ahci-hd,/images/disk.2 \
             -s 1:2,ahci-hd,/images/disk.3 \
             -s 1:3,ahci-hd,/images/disk.4 \
             -s 1:4,ahci-hd,/images/disk.5 \
             -s 1:5,ahci-hd,/images/disk.6 \
             -s 1:6,ahci-hd,/images/disk.7 \
             -s 1:7,ahci-hd,/images/disk.8 \
             -s 2,ahci-cd,/images/install.iso \
             -s 3,virtio-net,tap0 \
             -l com1,/dev/nmdm0A \
             -A -H -P -m 8G

SEE ALSO
     bhyve(4), nmdm(4), vmm(4), ethers(5), bhyvectl(8), bhyveload(8)

HISTORY
     bhyve first appeared in FreeBSD 10.0.

AUTHORS
     Neel Natu <neel@freebsd.org>
     Peter Grehan <grehan@freebsd.org>

FreeBSD 11.0-PRERELEASE         August 7, 2015         FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=bhyve&manpath=FreeBSD+10.3-RELEASE+and+Ports>

home | help