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 February 27, 2017 | .Dd April 9, 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 118 Lines • ▼ Show 20 Lines | |||||
.It Li ahci-hd | .It Li ahci-hd | ||||
AHCI controller attached to a SATA hard-drive. | AHCI controller attached to a SATA hard-drive. | ||||
.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 | |||||
Framebuffer device. | |||||
.It Li xhci | |||||
eXtensible Host Controller Interface (xHCI) USB controller. | |||||
.El | .El | ||||
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… | |||||
Not Done Inline ActionsAgreed, will roll back to your version. novel: Agreed, will roll back to your version. | |||||
.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 | ||||
Network devices: | Network devices: | ||||
▲ Show 20 Lines • Show All 94 Lines • ▼ Show 20 Lines | |||||
exits. | exits. | ||||
.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 | |||||
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 | |||||
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… | |||||
.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. | |||||
Done Inline ActionsYou need a comma between "height" and "respectively". bcr: You need a comma between "height" and "respectively". | |||||
If not specified, a default resolution of 1024x768 pixels will be used. | |||||
Done Inline ActionsProbably worth documenting the current max of 1920 x 1200 grehan: Probably worth documenting the current max of 1920 x 1200 | |||||
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 . | |||||
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… | |||||
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 | |||||
Done Inline Actionsditto here. bjk: ditto here.
(And the new sentence should start on a new line regardless.) | |||||
.Dq io | |||||
option should be used for guests that attempt to issue BIOS | |||||
Done Inline Actionss/the guests/guests bjk: s/the guests/guests | |||||
calls which result in I/O port queries, and fail to boot if I/O decode is disabled. | |||||
.Pp | |||||
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. | |||||
The | |||||
.Dq on | |||||
option should be used along with the CSM BIOS capability in UEFI | |||||
to boot traditional BIOS guests, so that complete I/O and memory decode | |||||
is present. | |||||
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. | |||||
.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 | |||||
Done Inline ActionsCould use .Lk for the link. bjk: Could use .Lk for the link. | |||||
.Pq Lk https://wiki.freebsd.org/bhyve | |||||
for configuration notes of particular guests. | |||||
.It wait | |||||
Instruct | |||||
.Nm | |||||
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. | |||||
.El | .El | ||||
.El | |||||
.Pp | |||||
xHCI USB devices: | |||||
.Bl -tag -width 10n | |||||
.It Li tablet | |||||
A USB tablet device which provides precise cursor synchronization | |||||
when using VNC. | |||||
.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 | ||||
.Pq UUID | .Pq UUID | ||||
in the guest's System Management BIOS System Information structure. | in the guest's System Management BIOS System Information structure. | ||||
Show All 31 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 | ||||
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 | ||||
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