Differential D10014 Diff 27995 head/usr.sbin/bhyve/bhyve.8

Changeset View

Standalone View

head/usr.sbin/bhyve/bhyve.8

Show All 18 Lines
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)		.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT		.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY		.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF		.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.		.\" SUCH DAMAGE.
.\"		.\"
.\" $FreeBSD$		.\" $FreeBSD$
.\"		.\"
.Dd April 27, 2017		.Dd May 3, 2017
.Dt BHYVE 8		.Dt BHYVE 8
.Os		.Os
.Sh NAME		.Sh NAME
.Nm bhyve		.Nm bhyve
.Nd "run a guest operating system inside a virtual machine"		.Nd "run a guest operating system inside a virtual machine"
.Sh SYNOPSIS		.Sh SYNOPSIS
.Nm		.Nm
.Op Fl abehuwxACHPSWY		.Op Fl abehuwxACHPSWY
.Op Fl c Ar numcpus		.Op Fl c Ar numcpus
.Op Fl g Ar gdbport		.Op Fl g Ar gdbport
.Op Fl l Ar lpcdev Ns Op , Ns Ar conf		.Op Fl l Ar lpcdev Ns Op , Ns Ar conf
.Op Fl m Ar memsize Ns Op Ar K\|k\|M\|m\|G\|g\|T\|t		.Op Fl m Ar memsize Ns Op Ar K\|k\|M\|m\|G\|g\|T\|t
.Op Fl p Ar vcpu:hostcpu		.Op Fl p Ar vcpu:hostcpu
.Op Fl s Ar slot,emulation Ns Op , Ns Ar conf		.Op Fl s Ar slot,emulation Ns Op , Ns Ar conf
.Op Fl U Ar uuid		.Op Fl U Ar uuid
.Ar vmname		.Ar vmname
.Sh DESCRIPTION		.Sh DESCRIPTION
.Nm		.Nm
is a hypervisor that runs guest operating systems inside a		is a hypervisor that runs guest operating systems inside a
virtual machine.		virtual machine.
.Pp		.Pp
Parameters such as the number of virtual CPUs, amount of guest memory, and		Parameters such as the number of virtual CPUs, amount of guest memory, and
I/O connectivity can be specified with command-line parameters.		I/O connectivity can be specified with command-line parameters.
.Pp		.Pp
The guest operating system must be loaded with		If not using a boot ROM, the guest operating system must be loaded with
.Xr bhyveload 8		.Xr bhyveload 8
or a similar boot loader before running		or a similar boot loader before running
.Nm .		.Nm ,
		otherwise, it is enough to run
		.Nm
		with a boot ROM of choice.
.Pp		.Pp
.Nm		.Nm
runs until the guest operating system reboots or an unhandled hypervisor		runs until the guest operating system reboots or an unhandled hypervisor
exit is detected.		exit is detected.
.Sh OPTIONS		.Sh OPTIONS
.Bl -tag -width 10n		.Bl -tag -width 10n
.It Fl a		.It Fl a
The guest's local APIC is configured in xAPIC mode.		The guest's local APIC is configured in xAPIC mode.
▲ Show 20 Lines • Show All 122 Lines • ▼ Show 20 Lines
.It Li uart		.It Li uart
PCI 16550 serial device.		PCI 16550 serial device.
.It Li lpc		.It Li lpc
LPC PCI-ISA bridge with COM1 and COM2 16550 serial ports and a boot ROM.		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.		The LPC bridge emulation can only be configured on bus 0.
.It Li fbuf		.It Li fbuf
Raw framebuffer device attached to VNC server.		Raw framebuffer device attached to VNC server.
.It Li xhci		.It Li xhci
XHCI USB controller.		eXtensible Host Controller Interface (xHCI) USB controller.
.El		.El
.It Op Ar conf		.It Op Ar conf
This optional parameter describes the backend for device emulations.		This optional parameter describes the backend for device emulations.
If		If
.Ar conf		.Ar conf
is not specified, the device emulation has no backend and can be		is not specified, the device emulation has no backend and can be
considered unconnected.		considered unconnected.
.Pp		.Pp
▲ Show 20 Lines • Show All 96 Lines • ▼ Show 20 Lines
.It		.It
There is no way to use the "console port" feature, nor the console port		There is no way to use the "console port" feature, nor the console port
resize at present.		resize at present.
.It		.It
Emergency write is advertised, but no-op at present.		Emergency write is advertised, but no-op at present.
.El		.El
.El		.El
.Pp		.Pp
Raw framebuffer device:		Framebuffer devices:
		.Bl -tag -width 10n
		.It Oo rfb= Ns Oo Ar IP: Oc Ns Ar port Oc Ns Oo ,w= Ns Ar width Oc Ns Oo ,h= Ns Ar height Oc Ns Oo ,vga= Ns Ar vgaconf Oc Ns Oo Ns ,wait Oc
		.Bl -tag -width 8n
		.It Ar IP:port
		An
		.Ar IP
		address and a
		.Ar port
		VNC should listen on.
		The default is to listen on localhost IPv4 address and default VNC port 5900.
		Listening on an IPv6 address is not supported.
		.It Ar width No and Ar height
		A display resolution, width and height, respectively.
		If not specified, a default resolution of 1024x768 pixels will be used.
		Minimal supported resolution is 640x480 pixels,
		and maximum is 1920x1200 pixels.
		.It Ar vgaconf
		Possible values for this option are
		.Dq io
		(default),
		.Dq on
		, and
		.Dq 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
		.Pq Ad 0x3c0-3df
		and memory space
		.Pq 64KB at Ad 0xA0000 .
		The default
		.Dq 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.
.Pp		.Pp
.Oo wait Oc Ns Oo ,vga= Ns Ar <on\|io\|off> Oc Oo ,rfb= Ns Oo Ar IP: Oc Ns Ar port Oc Ns Oo ,w= Ns Ar w Oc Ns Oo ,h= Ns Ar h Oc		The
.Bl -tag -width [vga=on\|io\|off]		.Dq 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.
		.Pp
		The
		.Dq 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
		.Ox
		in UEFI mode.
		.Pp
		Please refer to the
		.Nm
		.Fx
		wiki page
		.Pq Lk https://wiki.freebsd.org/bhyve
		for configuration notes of particular guests.
.It wait		.It wait
Wait for a VNC client connection before booting the virtual machine.		Instruct
The default is not to wait.		.Nm
.It vga= Ns Ar on\|io\|off		to only boot upon the initiation of a VNC connection, simplifying the installation
Enable VGA emulation.		of operating systems that require immediate keyboard input.
The default is		This can be removed for post-installation use.
.Va io
mode: VGA is enabled, but only I/O ports are available,
no VGA memory is provided.
.It rfb= Ns Oo Ar IP: Oc Ns Ar port
Set the VNC server to listen at
.Va IP:port .
The default is to listen on localhost IPv4 address and default VNC port 5900.
Listening on a IPv6 address is not supported.
.It w= Ns Ar width
Set framebuffer width to
.Ar width .
The default width is 1920.
.It h= Ns Ar height
Set framebuffer height to
.Ar height .
The default height is 1080.
.El		.El
		.El
.Pp		.Pp
XHCI USB controller device:		xHCI USB devices:
.Bl -tag		.Bl -tag -width 10n
.It Ar tablet		.It Li tablet
Emulate USB tablet mouse.		A USB tablet device which provides precise cursor synchronization
		when using VNC.
.El		.El
.El		.El
.It Fl S		.It Fl S
Wire guest memory.		Wire guest memory.
.It Fl u		.It Fl u
RTC keeps UTC time.		RTC keeps UTC time.
.It Fl U Ar uuid		.It Fl U Ar uuid
Set the universally unique identifier		Set the universally unique identifier
Show All 33 Lines
.It 1		.It 1
powered off		powered off
.It 2		.It 2
halted		halted
.It 3		.It 3
triple fault		triple fault
.El		.El
.Sh EXAMPLES		.Sh EXAMPLES
The guest operating system must have been loaded with		If not using a boot ROM, the guest operating system must have been loaded with
.Xr bhyveload 8		.Xr bhyveload 8
or a similar boot loader before		or a similar boot loader before
.Xr bhyve 4		.Xr bhyve 4
can be run.		can be run.
		Otherwise, the boot loader is not needed.
.Pp		.Pp
To run a virtual machine with 1GB of memory, two virtual CPUs, a virtio		To run a virtual machine with 1GB of memory, two virtual CPUs, a virtio
block device backed by the		block device backed by the
.Pa /my/image		.Pa /my/image
filesystem image, and a serial port for the console:		filesystem image, and a serial port for the console:
.Bd -literal -offset indent		.Bd -literal -offset indent
bhyve -c 2 -s 0,hostbridge -s 1,lpc -s 2,virtio-blk,/my/image \\		bhyve -c 2 -s 0,hostbridge -s 1,lpc -s 2,virtio-blk,/my/image \\
-l com1,stdio -A -H -P -m 1G vm1		-l com1,stdio -A -H -P -m 1G vm1
Show All 20 Lines	bhyve -c 4 \\
-s 1:0,ahci,hd:/images/disk.1,hd:/images/disk.2,\\		-s 1:0,ahci,hd:/images/disk.1,hd:/images/disk.2,\\
hd:/images/disk.3,hd:/images/disk.4,\\		hd:/images/disk.3,hd:/images/disk.4,\\
hd:/images/disk.5,hd:/images/disk.6,\\		hd:/images/disk.5,hd:/images/disk.6,\\
hd:/images/disk.7,hd:/images/disk.8,\\		hd:/images/disk.7,hd:/images/disk.8,\\
cd:/images/install.iso \\		cd:/images/install.iso \\
-s 3,virtio-net,tap0 \\		-s 3,virtio-net,tap0 \\
-l com1,/dev/nmdm0A \\		-l com1,/dev/nmdm0A \\
-A -H -P -m 8G		-A -H -P -m 8G
		.Ed
		.Pp
		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.
		.Bd -literal -offset indent
		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
.Ed		.Ed
.Sh SEE ALSO		.Sh SEE ALSO
.Xr bhyve 4 ,		.Xr bhyve 4 ,
.Xr nmdm 4 ,		.Xr nmdm 4 ,
.Xr vmm 4 ,		.Xr vmm 4 ,
.Xr ethers 5 ,		.Xr ethers 5 ,
.Xr bhyvectl 8 ,		.Xr bhyvectl 8 ,
.Xr bhyveload 8		.Xr bhyveload 8
.Sh HISTORY		.Sh HISTORY
.Nm		.Nm
first appeared in		first appeared in
.Fx 10.0 .		.Fx 10.0 .
.Sh AUTHORS		.Sh AUTHORS
.An Neel Natu Aq Mt neel@freebsd.org		.An Neel Natu Aq Mt neel@freebsd.org
.An Peter Grehan Aq Mt grehan@freebsd.org		.An Peter Grehan Aq Mt grehan@freebsd.org