Index: vmrun.8 =================================================================== --- /dev/null +++ vmrun.8 @@ -0,0 +1,192 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD +.\" +.\" Copyright (c) 2021 Tom Rhodes +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" 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 +.\" SUCH DAMAGE. +.\" +.Dd November 13, 2021 +.Dt vmrun 8 +.Os +.Sh NAME +.Nm vmrun +.Nd "bhyve wrapper script" +.Sh SYNOPSIS +.Nm +.Op Fl AETahiv +.Op Fl C Ar console +.Op Fl c Ar CPUs +.Op Fl d Ar disk image file +.Op Fl e Ar name Ns = Ns value +.Op Fl f Ar firmware path +.Op Fl F Ar size +.Op Fl H Ar directory +.Op Fl I Ar installation ISO location +.Op Fl l Ar loader +.Op Fl L Ar VNC IP for UEFI frambuffer +.Op Fl m Ar memory size +.Op Fl n Ar network adapter emulation type +.Op Fl P Ar port +.Op Fl t Ar tap device +guestname +.Sh DESCRIPTION +The +.Nm +script is a wrapper around the +.Xr bhyve 8 +.Fx +hypervisor and is located at +.Pa /usr/share/examples/bhyve/vmrun.sh . +It can be used to quickly create and power on a virtual machine guest. +The script attempts to restart the guest if it crashes or is rebooted. +This is done by running the guest in a loop. +The +.Nm +wrapper must be executed with super user privileges in order to create +and manage a guest. +Before starting a new guest, the +.Xr vmm 4 +device must be loaded into the kernel and a +.Xr tap 4 +device must be configured. +.Sh OPTIONS +.Bl -tag +.It Fl A +use AHCI disk emulation instead of the +.Xr virtio-blk 4 +device. +.It Fl a +Force memory-mapped local APIC access. +.It Fl C +Set the console device for the output of the virtual machine guest. +The default is +.stdio 3 . +.It Fl c Ar numcpus +Set the number of CPUs provided to the guest. +The default CPU count, if unspecified, is +.Qr 2 . +.It Fl d Ar disk image +The virtio disk device file to use. +This can be the path to an image file or the path to a disk +such as a zvol device. +.It Fl E +Use UEFI mode for the BIOS emulation. +.It Fl e Ar name Ns = Ns value +Set FreeBSD loader environment variables as a name=value parameter. +.It Fl F Ar size +Use a custom UEFI GOP framebuffer size, the default value is w=1024,h=768. +.It Fl f Ar firmware path +Use a specific UEFI firmware designated by +.Pa firmware path . +.It Fl H Ar directory +A host filesystem to export to the loader as the boot filesystem. +.It Fl h +Display a usage message. +.It Fl I Arfile.iso +Location of the installation CD-ROM ISO image. +.It Fl i +Force boot of the Installation CD-ROM image. +.It Fl L Ar VNC IP +IP address for UEFI GOP VNC server. +The default is 127.0.0.1. +.It Fl l Ar loader +The Operating System loader to use, the default is +.Pa /boot/userboot.so , +but the +.Nm grub2-bhyve +can also be used, for example, for Linux guests. +The +.Nm uefi-edk2-bhyve +port is also available. +.It Fl n Ar network emulation +The network adapter emulation type the guest will utilize. +By default, this is set to the +.Xr virtio 4 +virtio-net device. +.It Fl m Ar memory size +Specify the amount of memory for the guest. +The amount may be specified in human readable nomenclature such as 512M. +The default setting is 512M. +.It Fl P Ar port +The UEFI GOP VNC port to listen on for connections. +The default is 5900. +.It Fl p +Pass-through a host PCI device at bus/slot/func, for example, 10/1/2 +.It Fl T +Enable tablet device mode for UEFI GOP. +.It Fl t Ar tap device +The +.Xr tap 4 +device for virtio-net to utilize for network connectivity. +If a +.Xr tap 4 +was not specified in the command, a default of +.Cd tap0 +will be used. +.It Fl u +Set the real time clock to keep UTC time. +.It Fl v +Wait for a VNC client connection before booting the virtual machine. +.It Fl w +Ignore unimplemented MSRs. +.El +.Sh EXAMPLES +To quickly create a guest and start the +.Fx +installation process using an +.Fx +installation ISO file named +.Pa FreeBSD-12.2-RELEASE-amd64-bootonly.iso +with two CPUs, one gigabyte of memory, a +.Xr tap 4 +device named +.Pa tap0 +along with a +.Xr zfs +volume located at +.Pa /dev/zvol/zroot/freebsd-guest +as the disk device, issue the following command: +.Bd -literal -offset indent +sh /usr/share/examples/bhyve/vmrun.sh -c 1 -m 1024M +-t tap0 -d /dev/zvol/zroot/freebsd-guest -i -I +FreeBSD-12.2-RELEASE-amd64-bootonly.iso freebsd-guest +.Ed +.Sh SEE ALSO +.Xr dd 1 , +.Xr truncate 1 , +.Xr bhyve 4 , +.Xr tap 4 , +.Xr virtio_blk 4 , +.Xr bhyve_config 5 , +.Xr bhyve 8 . +.Sh HISTORY +The +.Xr bhyve 8 +.Fx +licensed hypervisor became part of the +.Fx +base system in the +.Fx +10.0 release. +.Sh AUTHORS +This manual page was was written by +.An Tom Rhodes Aq trhodes@FreeBSD.org .