| BHYVE(8) | MidnightBSD System Manager's Manual | BHYVE(8) |
bhyve — run a
guest operating system inside a virtual machine
bhyve |
[-AabCeHhPSuWwxY]
[-c [[cpus=]numcpus][,sockets=n][,cores=n][,threads=n]]
[-G port]
[-g gdbport]
[-l
lpcdev[,conf]]
[-m
memsize[K|k|M|m|G|g|T|t]]
[-p
vcpu:hostcpu]
[-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.
If not using a boot ROM, the guest operating system must be loaded
with bhyveload(8) or a
similar boot loader before running bhyve, otherwise,
it is enough to run bhyve with a boot ROM of
choice.
bhyve runs until the guest operating
system reboots or an unhandled hypervisor exit is detected.
-A-a-bdevice bvmconsole. This option is deprecated and
will be removed in FreeBSD 13.0.-C-c
[setting ...]-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.-G
portbhyve will pause execution at the first
instruction waiting for a debugger to attach.-g
gdbportdevice 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 is deprecated and will be removed in
FreeBSD 13.0.-H-h-k
file-l
help-l
lpcdev[,conf]bootrom, 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]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.
The default is 256M.
-o
var=value-P-p
vcpu-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 using a PCI
vendor ID of AMD.passthruvirtio-netvirtio-blkvirtio-scsivirtio-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.
Network device backends:
With virtio-net devices, the
mtu parameter can be specified to inform the
guest about the largest MTU that should be allowed, expressed in
bytes.
Block storage device backends:
,block-device-options],block-device-options]The block-device-options are:
nocacheO_DIRECT.directO_SYNC.rosectorsize=logical[/physical]SCSI device backends:
.vp][,scsi-device-options]The scsi-device-options are:
iid=IIDTTY device backends:
stdiobhyve process.Boot ROM device backends:
Pass-through device backends:
/bus/functionGuest 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 pptdevs loader variable as described in vmm(4).
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.Framebuffer devices backends:
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%zone]:portThe default is to listen on localhost IPv4 address and default VNC port 5900. An IPv6 address must be enclosed in square brackets and may contain an optional zone identifier.
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.
Please refer to the bhyve
FreeBSD wiki page
(https://wiki.freebsd.org/bhyve)
for configuration notes of particular guests.
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=passwordxHCI USB device backends:
tabletNVMe device backends:
,maxq=#][,qsz=#][,ioslots=#][,sectsz=#][,ser=#][,eui64=#][,dsm=opt]Configuration options are defined as follows:
ram=size_in_MiB.maxqqszioslotssectszsereui64dsmauto, enable, and
disable.AHCI device backends:
hd:|cd:]path][,nmrr=nmrr][,ser=#][,rev=#][,model=#]Configuration options are defined as follows:
nmrrserrevmodelHD Audio device backends:
play=playback][,rec=recording]Configuration options are defined as follows:
-U
uuid-u-W-w-x-YThe current debug server provides limited support for debuggers.
Each virtual CPU is exposed to the debugger as a thread.
General purpose registers can be queried for each virtual CPU, but other registers such as floating-point and system registers cannot be queried.
Memory (including memory mapped I/O regions) can be read by the debugger, but not written. Memory operations use virtual addresses that are resolved to physical addresses via the current virtual CPU's active address translation.
The running guest can be interrupted by the debugger at any time (for example, by pressing Ctrl-C in the debugger).
Single stepping is only supported on Intel CPUs supporting the MTRAP VM exit.
Breakpoints are supported on Intel CPUs that support single stepping. Note that continuing from a breakpoint while interrupts are enabled in the guest may not work as expected due to timer interrupts firing while single stepping over the breakpoint.
bhyve deals with the following
signals:
Exit status indicates how the VM was terminated:
If not using a boot ROM, the guest operating system must have been loaded with bhyveload(8) or a similar boot loader before bhyve(4) can be run. Otherwise, the boot loader is not needed.
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,hd:/images/disk.2,\ hd:/images/disk.3,hd:/images/disk.4,\ hd:/images/disk.5,hd:/images/disk.6,\ hd:/images/disk.7,hd:/images/disk.8,\ cd:/images/install.iso \ -s 3,virtio-net,tap0 \ -l com1,/dev/nmdm0A \ -A -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,ahci-hd,disk.img \ -s 5,virtio-net,tap0 \ -s 29,fbuf,tcp=0.0.0.0:5900,w=800,h=600,wait \ -s 30,xhci,tablet \ -s 31,lpc -l com1,stdio \ -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \ uefivm
Run a UEFI virtual machine with a VNC display that is bound to all IPv6 addresses on port 5900.
bhyve -c 2 -m 4G -w -H \ -s 0,hostbridge \ -s 4,ahci-hd,disk.img \ -s 5,virtio-net,tap0 \ -s 29,fbuf,tcp=[::]:5900,w=800,h=600 \ -s 30,xhci,tablet \ -s 31,lpc -l com1,stdio \ -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \ uefivm
bhyve(4), nmdm(4), vmm(4), ethers(5), bhyvectl(8), bhyveload(8)
Intel, 64 and IA-32 Architectures Software Developer’s Manual, Volume 3.
bhyve first appeared in
FreeBSD 10.0.
Neel Natu
<neel@freebsd.org>
Peter Grehan
<grehan@freebsd.org>
| April 18, 2021 | midnightbsd-3.1 |