Changeset View
Standalone View
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 April 28, 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 | ||||
grehan: using a boot ROM | |||||
.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 120 Lines • ▼ Show 20 Lines | |||||
.It Li e1000 | .It Li e1000 | ||||
Intel e82545 network interface. | Intel e82545 network interface. | ||||
.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. | Framebuffer device. | ||||
glebiusUnsubmitted Not Done Inline ActionsI think my description was better. Without details on VNC the description is too bare. What is our side of framebuffer device? May be it is just memory region to emulate VGA, that does nothing instead of providing VGA device to the guest? glebius: I think my description was better. Without details on VNC the description is too bare. What is… | |||||
novelAuthorUnsubmitted Not Done Inline ActionsAgreed, will roll back to your version. novel: Agreed, will roll back to your version. | |||||
.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 rfb= Ns Ar host:port Ns Oo , Ns w= Ns Ar width Ns ,h= Ns Ar height Oc Ns Oo ,vga= Ns Ar vgaconf Oc Ns Oo Ns ,wait Oc | |||||
.Bl -tag -width 8n | |||||
.It Ar host:port | |||||
A | |||||
.Ar host | |||||
and a | |||||
.Ar port | |||||
VNC should listen on. | |||||
.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 | ||||
Not Done Inline Actions"tcp=" will be deprected. bhyve currenctly accepts "rfb" for the VNC protocol so that one should be documented. grehan: "tcp=" will be deprected. bhyve currenctly accepts "rfb" for the VNC protocol so that one… | |||||
Not Done Inline ActionsOh, it's unfortunate that 'tcp=' is getting deprecated as I'm using that in the libvirt driver already. Is there a way to detect that in runtime? I can see that bhyve *can* report unsupported configuration for the fbuf device, but that happens pretty late in the VM creation process, i.e. I have to run in this way: /usr/sbin/bhyve -m 2048 -s 4:0,fbuf,tcp=127.0.0.1:5904,oops test It does not work if I omit "-m" and guest name. Also, it creates /dev/vmm/test, so I have to call destroy on it, which makes such kind of a probe a little expensive. PS In a message "Invalid fbuf emulation "oops" fbuf: {wait,}{vga=on|io|off,}rfb=<ip>:port" do commas have to go after the closing brace to follow common style? novel: Oh, it's unfortunate that 'tcp=' is getting deprecated as I'm using that in the libvirt driver… | |||||
Not Done Inline ActionsThe width, height and wait parameters are optional. Width/height defaults to 1024x768, with a minimum of 640x480. Another optional parameter is "vga=[on|io|off]", which controls whether the frame buffer exports standard VGA registers. Windows 7/2k8 guests require "io", which is the default. "on" should be used when using graphics with BIOS guests, and "off" is required for OpenBSD UEFI guests to prevent the early probe from assuming a VGA framebuffer is present. grehan: The width, height and wait parameters are optional. Width/height defaults to 1024x768, with a… | |||||
Not Done Inline ActionsIs there probably some general description of the "io" option? Also, are there any rules regarding mentioning Windows in the manual pages, i.e. should we put stuff like (tm) or (r) or anything like that? The first thing that came to my mind is wine(1) and it just goes with "Windows $Ver", though it's not a part of the FreeBSD base. novel: Is there probably some general description of the "io" option? Also, are there any rules… | |||||
Not Done Inline ActionsPCI 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). A true non-legacy UEFI-only graphics adapter doesn't require any of the legacy decodes. However, Windows 7 and 2k8 still attempt to issue BIOS calls which result in i/o port queries. If the i/o decode is disabled, the Windows guest will fail to boot. This corresponds to the "vga=io" mode. Regarding explicit references to Windows - that could be changed to "some guests" and the FreeBSD wiki used to demonstrate options for particular guests. I can just leave "tcp=" in the code. But, best not to document it. I know we've chatted about ways to try and determine what features are available at run-time. Let me think a bit more about that. When using the CSM BIOS compatibility in UEFI to boot traditional BIOS guests, the complete i/o and memory decode needs to be present ("vga=on"). OpenBSD in UEFI mode will detect i/o ports and assume a VGA adapter is present. To prevent this, the "vga=off" mode is provided. Note that picking a default will prevent either Windows or OpenBSD from functioning. Since Win7 seems very prevalent, the default was selected to allow that. grehan: PCI graphics cards have a dual personality in that they are standard PCI devices with BAR… | |||||
Not Done Inline ActionsThanks for a great explanation! I've tried to summarize it up using the powerful copy/paste technique. Hopefully I didn't mess up with with the rest. novel: Thanks for a great explanation! I've tried to summarize it up using the powerful copy/paste… | |||||
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 | ||||
.Pq UUID | .Pq UUID | ||||
in the guest's System Management BIOS System Information structure. | in the guest's System Management BIOS System Information structure. | ||||
By default a UUID is generated from the host's hostname and | By default a UUID is generated from the host's hostname and | ||||
.Ar vmname . | .Ar vmname . | ||||
.It Fl w | .It Fl w | ||||
Ignore accesses to unimplemented Model Specific Registers (MSRs). | Ignore accesses to unimplemented Model Specific Registers (MSRs). | ||||
Done Inline ActionsYou need a comma between "height" and "respectively". bcr: You need a comma between "height" and "respectively". | |||||
This is intended for debug purposes. | This is intended for debug purposes. | ||||
Done Inline ActionsProbably worth documenting the current max of 1920 x 1200 grehan: Probably worth documenting the current max of 1920 x 1200 | |||||
.It Fl W | .It Fl W | ||||
Force virtio PCI device emulations to use MSI interrupts instead of MSI-X | Force virtio PCI device emulations to use MSI interrupts instead of MSI-X | ||||
interrupts. | interrupts. | ||||
.It Fl x | .It Fl x | ||||
The guest's local APIC is configured in x2APIC mode. | The guest's local APIC is configured in x2APIC mode. | ||||
.It Fl Y | .It Fl Y | ||||
Disable MPtable generation. | Disable MPtable generation. | ||||
.It Ar vmname | .It Ar vmname | ||||
Alphanumeric name of the guest. | Alphanumeric name of the guest. | ||||
Done Inline ActionsIt is very strange to see zero-width-space+'.' on its own line like this. bjk: It is very strange to see zero-width-space+'.' on its own line like this.
".Dq off ." all on… | |||||
This should be the same as that created by | This should be the same as that created by | ||||
.Xr bhyveload 8 . | .Xr bhyveload 8 . | ||||
.El | .El | ||||
.Sh SIGNAL HANDLING | .Sh SIGNAL HANDLING | ||||
.Nm | .Nm | ||||
deals with the following signals: | deals with the following signals: | ||||
.Pp | .Pp | ||||
Done Inline Actionsditto here. bjk: ditto here.
(And the new sentence should start on a new line regardless.) | |||||
.Bl -tag -width indent -compact | .Bl -tag -width indent -compact | ||||
.It SIGTERM | .It SIGTERM | ||||
Done Inline Actionss/the guests/guests bjk: s/the guests/guests | |||||
Trigger ACPI poweroff for a VM | Trigger ACPI poweroff for a VM | ||||
.El | .El | ||||
Not Done Inline Actionsmdoc.9 says "This macro should not be used" about .br; I *think* .Pp will work fine within the list environment. bjk: mdoc.9 says "This macro should not be used" about .br; I *think* .Pp will work fine within the… | |||||
Not Done Inline ActionsYeah, and it even looks nicer with .Pp instead of .br. novel: Yeah, and it even looks nicer with .Pp instead of .br. | |||||
.Sh EXIT STATUS | .Sh EXIT STATUS | ||||
Exit status indicates how the VM was terminated: | Exit status indicates how the VM was terminated: | ||||
.Pp | .Pp | ||||
.Bl -tag -width indent -compact | .Bl -tag -width indent -compact | ||||
.It 0 | .It 0 | ||||
Not Done Inline ActionsI don't think I understand this sentence. Is there another word that can go with "memory decode is present" to clarify what exactly is present -- the decoded memory itself, or the ability to decode memory, or ...? bjk: I don't think I understand this sentence. Is there another word that can go with "memory… | |||||
Not Done Inline ActionsI *think* that's "the ability to decode ...". Though I hope Peter could suggest something on that as he's clearly more familiar with the topic. novel: I *think* that's "the ability to decode ...". Though I hope Peter could suggest something on… | |||||
Not Done Inline Actions@grehan could you please help with this one? novel: @grehan could you please help with this one? | |||||
Not Done Inline ActionsHow about "to boot traditional BIOS guests that require the legacy VGA I/O and memory regions to be available" grehan: How about "to boot traditional BIOS guests that require the legacy VGA I/O and memory regions… | |||||
Not Done Inline ActionsThat sounds good to me, thanks. bjk: That sounds good to me, thanks. | |||||
rebooted | rebooted | ||||
.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 | ||||
Done Inline Actionsusing a boot ROM grehan: using a boot ROM | |||||
.Xr bhyveload 8 | .Xr bhyveload 8 | ||||
or a similar boot loader before | or a similar boot loader before | ||||
.Xr bhyve 4 | .Xr bhyve 4 | ||||
Done Inline ActionsCould use .Lk for the link. bjk: Could use .Lk for the link. | |||||
can be run. | can be run. | ||||
Otherwise, the boot loader is not needed. | |||||
Done Inline ActionsOtherwise, the boot loader is not needed. grehan: Otherwise, the boot loader is not needed. | |||||
Done Inline ActionsThis does not seem to be "done" yet. bcr: This does not seem to be "done" yet. | |||||
Not Done Inline ActionsOops, I've added the comma after "otherwise", but didn't pay attention to the missing "the". Should be fine now, thanks for noting. novel: Oops, I've added the comma after "otherwise", but didn't pay attention to the missing "the". | |||||
.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 | |||||
Done Inline ActionsI would add "pixels" after the 600. bcr: I would add "pixels" after the 600. | |||||
Done Inline ActionsThese things are always somewhat contentious, but I would pronounce "UEFI" as "You ee eff aye", which corresponds to just "a UEFI". bjk: These things are always somewhat contentious, but I would pronounce "UEFI" as "You ee eff aye"… | |||||
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 |
using a boot ROM