| BHYVE(8) | Maintenance Commands and Procedures | BHYVE(8) |
bhyve — run a
guest operating system inside a virtual machine
bhyve |
[-aCDdeHhPSuWwxY]
[-c [[cpus=]numcpus][,sockets=n][,cores=n][,threads=n]]
[-f
name,[string|file]=data]
[-G [w][bind_address:]port]
[-B
type,[key=value][,key=value]...]
[-k config_file]
[-K layout]
[-l
lpcdev[,conf]]
[-m memsize[K|k|M|m|G|g|T|t]]
[-o
var=value]
[-r file]
[-s slot,emulation[,conf]]
[-U uuid]
vmname |
bhyve |
-l help |
bhyve |
-s help |
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.
bhyve runs until the guest operating
system reboots or an unhandled hypervisor exit is detected.
-a-B
type,[key=value][,key=value]...0, 1,
2 or 3. Supported keys for
each type are:
0vendor,
version,
release_date.1manufacturer,
product_name (or
product), version,
serial_number (or
serial), sku,
family_name (or
family), uuid.2manufacturer,
product_name, version,
serial_number,
asset_tag,
location3manufacturer,
version,
serial_number, asset_tag,
sku.-c
[[cpus=]numcpus][,sockets=n][,cores=n][,threads=n]-C-D-d-ebhyve to exit when a guest issues an access
to an I/O port that is not emulated. This is intended for debug
purposes.-f
name,[string|file]=datastring is specified, the fw_cfg file contains the
string as data. If a file is specified, bhyve
reads the file and adds the file content as fw_cfg data.-G
[w][bind_address:]portbhyve will pause execution at the first
instruction waiting for a debugger to attach.-H-h-k
config_file-K
layout-l
help-l
lpcdev[,conf]com1,
com2, com3 and
com4, the TPM module tpm,
the boot ROM device bootrom, the
fwcfg type and the debug/test device
pc-testdev.
The possible values for the conf
argument are listed in the -s flag
description.
-m
memsize[K|k|M|m|G|g|T|t]K, M,
G or T (either upper or
lower case) to indicate a multiple of kibibytes, mebibytes, gibibytes, or
tebibytes. If no suffix is given, the value is assumed to be in mebibytes.
The default is 256MiB.
-o
var=value-P-S-s
help-s
slot,emulation[,conf]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.
The slot can be specified in one of the following formats:
:function:pcislot:functionThe 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.
The emulation argument can be one of the following:
hostbridgeamd_hostbridgehostbridge but using a
PCI vendor ID of AMD.passthruvirtio-net-vionavirtio-netvirtio-blkvirtio-9pvirtio-rndvirtio-consoleahciahci-cdahci-hde1000uartlpcfbufxhcinvmeThe optional parameter conf describes the backend for device emulations. If conf is not specified, the device emulation has no backend and can be considered unconnected.
model=modelnetapp.vendor=vendordevid=devidProviding extra configuration parameters for a host bridge is optional, but if parameters are provided then either model by itself, or both of vendor and devid must be specified.
Accelerated Virtio Network Backends:
vnic=]vnic[,feature_mask=mask]vnic is the name of a configured virtual NIC on the system. mask is applied to the virtio feature flags which are advertised to the guest. Bits set in the mask value are removed from the advertised features.
vnic=]vnic[,network-backend-options]vnic is the name of a configured virtual NIC on the system.
The network-backend-options are:
promiscphyspromiscsappromiscmultipromiscrxonlyBlock storage device backends:
,block-device-options],block-device-options]The block-device-options are:
nocacheO_DIRECT.directO_SYNC.rosectorsize=logical[/physical]nodeleteDIOCGDELETE requests.bootindex=index=/path/to/share[,9p-device-options]The 9p-device-options are:
rostdiobhyve process.TPM device backends:
,tpm-device-options]The tpm-device-options are:
version=version2.0,varfile]Fwcfg types:
bhyve’ and
‘qemu’. Due to backward
compatibility reasons, ‘bhyve’
is the default option. When
‘bhyve’ is used, bhyve's fwctl
interface is used. It currently reports only the CPU count to the
guest firmware. The ‘qemu’
option uses QEMU's fwcfg interface. This interface is widely used and
allows user-defined information to be passed o the guest. It is used
for passing the CPU count, ACPI tables, a boot order and many other
things to the guest. Some operating systems such as Fedora CoreOS can
be configured by qemu's fwcfg interface as well.rom=romfilebootindex=indexGuest memory must be wired using the
-S option when a pass-through device is
configured.
The host device must have been previously attached to the ppt driver.
Virtio console device backends:
port1=/path/to/port1.sock[,portN=/path/to/port2.sock ...]A maximum of 16 ports per device can be created. Every port is
named and corresponds to a UNIX domain socket created by
bhyve. bhyve accepts at
most one connection per port at a time.
Limitations:
bhyve, sockets
on the filesystem must be cleaned up manually after
bhyve exits.TPM devices:
Supported types:
version=versionSupported versions:
rfb=ip-and-port][,w=width][,h=height][,vga=vgaconf][,wait][,password=password]Configuration options are defined as follows:
rfb=ip-and-port
(or tcp=ip-and-port):]port[IPv6]:portThe default is to listen on localhost IPv4 address and default VNC port 5900. An IPv6 address must be enclosed in square brackets.
unix=pathbhyve will accept VNC connections.w=width
and
h=heightvga=vgaconfio
(default), on , and
off. PCI graphics cards have a dual
personality in that they are standard PCI devices with BAR addressing,
but may also implicitly decode legacy VGA I/O space
(0x3c0-3df) and memory space (64KB at
0xA0000). The default
io option should be used for guests that
attempt to issue BIOS calls which result in I/O port queries, and fail
to boot if I/O decode is disabled.
The on option should be used along
with the CSM BIOS capability in UEFI to boot traditional BIOS guests
that require the legacy VGA I/O and memory regions to be
available.
The off option should be used for
the UEFI guests that assume that VGA adapter is present if they
detect the I/O ports. An example of such a guest is
OpenBSD in UEFI mode.
waitbhyve to only boot upon the
initiation of a VNC connection, simplifying the installation of
operating systems that require immediate keyboard input. This can be
removed for post-installation use.password=passwordtablet,maxq=#][,qsz=#][,ioslots=#][,sectsz=#][,ser=#][,eui64=#][,dsm=opt]Configuration options are defined as follows:
ram=size_in_MiB.maxqqszioslotssectszsereui64dsmauto, enable, and
disable.hd:|cd:]path][,nmrr=nmrr][,ser=#][,rev=#][,model=#]Configuration options are defined as follows:
-U
uuid-u-W-w-x-Ybhyve uses an internal tree of
configuration variables to describe global and per-device settings. When
bhyve starts, it parses command line options
(including config files) in the order given on the command line. Each
command line option sets one or more configuration variables. For example,
the -s option creates a new tree node for a PCI
device and sets one or more variables under that node including the device
model and device model-specific variables. Variables may be set multiple
times during this parsing stage with the final value overriding previous
values.
Once all of the command line options have been processed, the
configuration values are frozen. bhyve then uses the
value of configuration values to initialize device models and global
settings.
More details on configuration variables can be found in bhyve_config(5).
bhyve deals with the following
signals:
Exit status indicates how the VM was terminated:
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 -H -P -m 1G vm1
Run a 24GB single-CPU virtual machine with three network ports.
bhyve -s 0,hostbridge -s 1,lpc -s 2:0,virtio-net-viona,vmvnic0 \ -s 2:1,virtio-net-viona,vmvnic1 -s 2:2,virtio-net-viona,vmvnic2 \ -s 3,virtio-blk,/my/image -l com1,stdio \ -H -P -m 24G bigvm
Run an 8GB virtual machine with 2 quad core CPUs, 2 NVMe disks and one other disk attached as a Virtio block device, an AHCI ATAPI CD-ROM, a single viona network port, an i440fx hostbridge, and the console port connected to a socket.
bhyve -c sockets=2,cores=4,threads=2 \ -s 0,hostbridge,model=i440fx -s 1,lpc \ -s 1:0,nvme,/dev/zvol/rdsk/tank/hdd0 \ -s 1:1,nvme,/dev/zvol/rdsk/tank/hdd1 \ -s 1:2,virtio-blk,/dev/zvol/rdsk/tank/hdd1 \ -s 2:0,ahci,cd:/images/install.iso \ -s 3,virtio-net-viona,vnic=vmvnic0 \ -l com1,socket,/tmp/vm.com1,wait \ -H -P -m 8G
Run a UEFI virtual machine with a display resolution of 800 by 600 pixels that can be accessed via VNC at: 0.0.0.0:5900.
bhyve -c 2 -m 4G -w -H \ -s 0,hostbridge \ -s 3,ahci-cd,/path/to/uefi-OS-install.iso \ -s 4,nvme,/dev/zvol/rdsk/tank/hdd0 \ -s 5,virtio-net-viona,vnic=vnmic0 \ -s 29,fbuf,vga=off,rfb=0.0.0.0:5900,w=800,h=600,wait \ -s 30,xhci,tablet \ -s 31,lpc -l com1,stdio \ -l bootrom,/usr/share/bhyve/firmware/BHYVE_UEFI.fd \ uefivm
Run a UEFI virtual machine with a VARS file to save EFI variables.
Note that bhyve will write guest modifications to
the given VARS file. Be sure to create a per-guest copy of the template VARS
file from /usr/share/bhyve/firmware.
bhyve -c 2 -m 4g -w -H \ -s 0,hostbridge \ -s 31,lpc -l com1,stdio \ -l bootrom,/usr/share/bhyve/firmware/BHYVE_UEFI.fd,BHYVE_UEFI_VARS.fd \ uefivm
Intel, 64 and IA-32 Architectures Software Developers' Manual, Volume 3.
| May 5, 2023 | OmniOS |