iohyve.8

.\" Text automatically generated by txt2man
.TH iohyve 8 "30 May 2016" "" "FreeBSD System Manager's Manual"
.SH NAME
\fBiohyve\fP- bhyve manager/launcher
\fB
.SH SYNOPSIS
.nf
.fam C
\fBiohyve\fP \fIversion\fP
\fBiohyve\fP \fIsetup\fP <pool=poolname> [kmod=0|1] [\fInet=iface\fP]
\fBiohyve\fP \fIlist\fP [\fB-l\fP]
\fBiohyve\fP \fIinfo\fP [\fB-vsdl\fP]
\fBiohyve\fP \fIisolist\fP
\fBiohyve\fP \fIfwlist\fP
\fBiohyve\fP \fIfetchiso\fP <URL>
\fBiohyve\fP \fIcpiso\fP <path>
\fBiohyve\fP \fIrenameiso\fP <ISO> <newname>
\fBiohyve\fP \fIrmiso\fP <ISO>
\fBiohyve\fP \fIfetchfw\fP <URL>
\fBiohyve\fP \fIcpfw\fP <path>
\fBiohyve\fP \fIrenamefw\fP <firmware> <newname>
\fBiohyve\fP \fIrmfw\fP <firmware>
\fBiohyve\fP \fIcreate\fP <name> <size> [\fIpool\fP]
\fBiohyve\fP \fIinstall\fP <name> <ISO>
\fBiohyve\fP \fIload\fP <name>
\fBiohyve\fP \fIboot\fP <name> <ISO>
\fBiohyve\fP \fIstart\fP <name> [\fB-a\fP | \fB-s\fP]
\fBiohyve\fP \fIstop\fP <name>
\fBiohyve\fP \fIforcekill\fP <name>
\fBiohyve\fP \fIscram\fP
\fBiohyve\fP \fIdestroy\fP <name>
\fBiohyve\fP \fIrename\fP <name> <newname>
\fBiohyve\fP \fIdelete\fP [\fB-f\fP] <name>
\fBiohyve\fP \fIset\fP <name> <property=value> \.\.\.
\fBiohyve\fP \fIget\fP <name> <prop>
\fBiohyve\fP \fIrmpci\fP [\fB-f\fP] <name> <pcidev:N>
\fBiohyve\fP \fIgetall\fP <name>
\fBiohyve\fP \fIadd\fP <name> <size> [\fIpool\fP]
\fBiohyve\fP \fIremove\fP [\fB-f\fP] <name> <diskN>
\fBiohyve\fP \fIresize\fP <name> <diskN> <size>
\fBiohyve\fP \fIdisks\fP <name>
\fBiohyve\fP \fIsnap\fP <name>@<\fIsnap\fP>
\fBiohyve\fP \fIroll\fP <name>@<\fIsnap\fP>
\fBiohyve\fP \fIclone\fP [\fB-r\fP] <name> <clonename>
\fBiohyve\fP \fIexport\fP <name>
\fBiohyve\fP \fIsnaplist\fP
\fBiohyve\fP \fItaplist\fP
\fBiohyve\fP \fIactivetaps\fP
\fBiohyve\fP \fIconlist\fP
\fBiohyve\fP \fIconsole\fP <name>
\fBiohyve\fP \fIconreset\fP
\fBiohyve\fP \fIhelp\fP
\fBiohyve\fP \fIman\fP

.fam T
.fi
.fam T
.fi
.SH DESCRIPTION
The \fBiohyve\fP shell script utilizes the FreeBSD hypervisor \fBbhyve\fP(8),
\fBzfs\fP(8), and \fBnmdm\fP(4) to make virtualization on FreeBSD easy and simple.
The basic idea is to store bhyve settings in zfs user properties of zfs
datasets that house important guest files like block devices and grub
configurations. \fBiohyve\fP(8) uses the virtio drivers built into the GENERIC
kernel for virtualization.
.RE
.PP

.SH OPTIONS
.TP
.B
\fIversion\fP
Prints the current running \fIversion\fP of \fBiohyve\fP.
.TP
.B
\fIsetup\fP
Installs required zfs datasets and kernel modules for \fBiohyve\fP.
Usage: '\fBiohyve\fP \fIsetup\fP <\fIpool\fP=poolname> [kmod=0|1] [\fInet=iface\fP]'
where <poolname> is the \fIpool\fP you want to \fIinstall\fP \fBiohyve\fP on,
kmod=<0|1> is if you want \fBiohyve\fP to \fIload\fP or unload the
kernel modules required by \fBiohyve\fP. 1 is \fIload\fP. net=<iface>
will \fIset\fP up the network bridge to the specified interface.
Multiple pools are supported, additional pools \fIget\fP mounted
in /\fBiohyve\fP/poolname
.TP
.B
\fIlist\fP
Lists the name, status for VMM, active bhyve (Running), \fIboot\fP
on \fIstart\fP flag (rcboot), and description for each guest.
.RS
.PP
\fB-l\fP flag pipes the final output to less
.RE
.TP
.B
\fIinfo\fP
Lists properties about the guests and their \fIdisks\fP using flags
to control level of output. Fields include CPU count, RAM, Disk
Size, Pool, OS, Loader, Tap, Console, VMM status, Running status,
rcboot flag, \fIpool\fP, and the description. Use \fB-l\fP to pipe to less.
.RS
.PP
\fB-v\fP is for verbose which adds the fields: OS,
Loader, Tap, and Con.
.PP
\fB-s\fP is for status which \fIadd\fP the fields: VMM,
Running, and rcboot.
.PP
\fB-d\fP is for description. Shows the guest description.
.PP
\fB-l\fP is for less and pipes the final output to less.
.PP
Order of flags is not important. The proper syntax is to use
the flags contiguously. So "\fB-ld\fP" is the correct way to display
the base output plus description, and then have the output
piped to less.
.RE
.TP
.B
\fIisolist\fP
Lists the installed ISOs in the /\fBiohyve\fP/ISO directory.
.TP
.B
\fIfwlist\fP
Lists the firmwares in the /\fBiohyve\fP/Firmware directory.
.TP
.B
\fIfetchiso\fP
Fetches installation ISO or \fIinstall\fP image and creates a
dataset for it.
Usage: '\fBiohyve\fP \fIfetchiso\fP <URL>' where <URL> is the HTTP or FTP URL to
\fIfetchiso\fP from the internet.
.TP
.B
\fIcpiso\fP
Copies installation ISO or \fIinstall\fP image from your host and
creates a dataset for it.
Usage: '\fBiohyve\fP \fIcpiso\fP <path>' where <path> is the full path to
ISO file on the host machine.
.TP
.B
\fIrenameiso\fP
Renames an ISO.
Usage: '\fBiohyve\fP \fIrenameiso\fP <ISO> <newname>' where <ISO> is the
name of the ISO you would like to \fIrename\fP. <newname>
is a new name.
.TP
.B
\fIrmiso\fP
Removes installed ISO from /\fBiohyve\fP/ISO.
Usage: '\fBiohyve\fP \fIrmiso\fP <ISO>' where <ISO> is the name of the ISO
you would like to \fIdelete\fP.
.TP
.B
\fIfetchfw\fP
Fetches firmware and creates a dataset for it.
Usage: '\fBiohyve\fP \fIfetchfw\fP <URL>' where <URL> is the HTTP or FTP URL to
fetch from the internet.
.TP
.B
\fIcpfw\fP
Copies firmware from your host and creates a dataset for it.
Usage: '\fBiohyve\fP \fIcpfw\fP <path>' where <path> is the full path to
firmware file on the host machine.
.TP
.B
\fIrenamefw\fP
Renames a firmware.
Usage: '\fBiohyve\fP \fIrenamefw\fP <firmware> <newname>' where <firmware>
is the name of the firmware you would like to \fIrename\fP.
<newname> is a new name.
.TP
.B
\fIrmfw\fP
Removes installed firmware from /\fBiohyve\fP/Firmware.
Usage: '\fBiohyve\fP \fIrmfw\fP <firmware>' where <firmware> is the name of
the firmware you would like to \fIdelete\fP.
.TP
.B
\fIcreate\fP
Creates new guest operating system.
Usage: '\fBiohyve\fP \fIcreate\fP <name> <size> [\fIpool\fP]' where <name> is
the name you would like to use, <size> is the size of the
virtual block device in '16G' format where the capital G
signifies gigabytes. If you specify the \fIpool\fP, the first disk
gets added on that \fIpool\fP.
.TP
.B
\fIinstall\fP
Loads and boots into ISO for guest installation.
Usage: '\fBiohyve\fP \fIinstall\fP <name> <ISO>' where <name> is the name
of the guest, and [ISO] is the name of the ISO you would
like to \fIboot\fP from in the form of: 'install.iso'
.TP
.B
\fIload\fP
Loads the guest operating system bootloader and resources.
Usage: '\fBiohyve\fP \fIload\fP <name> <ISO>'
where <name> is the name of the guest operating system.
<ISO> is the path to the \fIboot\fP medium
.TP
.B
\fIboot\fP
Boots the guest into the operating system. '\fBiohyve\fP run' needs
to be run before this is done.
Usage: '\fBiohyve\fP \fIboot\fP <name> <runmode> <pci>'
where <name> is the name of the guest operating system.
<runmode> describes how to \fIstart\fP the guest:
0 = \fIstart\fP only once
1 = regular persist
Stop if the guest is powering off
2 = always persist
Always restart the guest
<pci> is a space separated \fIlist\fP of pci devices
based on slot-less bhyve \fB-s\fP commands.
Example:
"ahci-hd,/path/disk.img virtio-net,tap0"
Note: hostbridge and lpc are automatically
added
.TP
.B
\fIstart\fP
Starts the guest operating system. (Combines \fIload\fP & \fIboot\fP)
Usage: '\fBiohyve\fP \fIstart\fP <name> [\fB-s\fP | \fB-a\fP]'
where <name> is the name of the guest operating system.
[\fB-s\fP] will cause the guest to be started once
[\fB-a\fP] will cause the guest to always restart
.TP
.B
\fIstop\fP
Gracefully stops guest operating system.
Usage: '\fBiohyve\fP \fIstop\fP <name>' where <name> is the name
of the guest operating system.
.TP
.B
\fIforcekill\fP
Forces the guest to \fIstop\fP. Runs kill \fB-9\fP and destroys the guest
in VMM. USE WITH EXTREME CAUTION AND AS A LAST RESORT. Can be
used to kill guests stuck at the GRUB \fIconsole\fP that you
do not have access to.
.TP
.B
\fIscram\fP
Gracefully \fIstop\fP all bhyve guests. Does not \fIdestroy\fP resources.
.TP
.B
\fIdestroy\fP
Destroys guest resources.
Usage: '\fBiohyve\fP \fIdestroy\fP <name>' where <name> is the name
of the guest operating system. Destroying a guest does
not \fIdelete\fP a guest from the host, it destroys the guest in VMM.
.TP
.B
\fIrename\fP
Renames the guest.
Usage: '\fBiohyve\fP \fIrename\fP <name> <newname>' where <name> is the
name of the guest and <newname> is the new name.
.TP
.B
\fIdelete\fP
Deletes all data for the guest.
Usage: '\fBiohyve\fP \fIdelete\fP <name>' where <name> is the name
of the guest operating system. If [\fB-f\fP] is supplied before the
<name>, there is no prompt to \fIdelete\fP.
.TP
.B
\fIset\fP
Sets ZFS properties for guests one at a time.
Usage: '\fBiohyve\fP \fIset\fP <name> <property=value> \.\.\.' where
<name> is the name of the guest operating system.
Properties:
ram=512M or ram=2G (M for megabytes, G for gigabtyes)
cpu=1 (number of cpu cores)
con=nmdm0 (where to attach null modem \fIconsole\fP)
tap=tap[n](,tap[n]) (tap device for virtio-net)
[n] is a generic number to specify the tap interface to use.
Specify a \fIlist\fP of tap devices separated by comma for multiple tap
Single tap: \fBiohyve\fP \fIset\fP [name] tap=tap0.
Multiple tap : \fBiohyve\fP \fIset\fP [name] tap=tap0,tap1,tap2,tap3
size=size of block device
mac_tap[n]=[MAC Address]
[n] is a generic number to specify the tap interface to use
Forces a specific MAC address to be attached to the
network adapter in the guest OS. \fBiohyve\fP does not check
for a valid MAC address, so double check the property.
pcidev:[n]=<spec>
Generic way to \fIadd\fP devices to the guest.
[n] is a generic random number or string
<spec> defines a virtual device added to the guest
by using a bhyve \fB-s\fP argument without the pcislot
or function argument. PCI slot numbers are assigned
automatically by \fBiohyve\fP.
Examples: "pcidev:1=passthru,2/0/0"
"pcidev:2=ahci-hd,/some/place/disk.img"
.TP
.B
\fIget\fP
Gets ZFS properties for guests one at a time.
Usage: '\fBiohyve\fP \fIget\fP <name> <prop>' where <name> is the name
of the guest operating system. <prop> is the
property you want to view. (See '\fBiohyve\fP \fIset\fP' \fIinfo\fP)
.TP
.B
\fIrmpci\fP
Removes a pcidev from the guest.
Usage: '\fBiohyve\fP \fIrmpci\fP <name> <pcidev:N>' where <name> is the name
of the guest operating system. <pcidev:N> is the PCI
device you want removed. Ex: 'pcidev:3' If [\fB-f\fP] is supplied
before the <name>, there is no prompt to \fIremove\fP.
.TP
.B
\fIgetall\fP
Gets all the ZFS properties for a guest.
Usage: '\fBiohyve\fP \fIgetall\fP <name>' where <name> is the name
of the guest operating system.
.TP
.B
\fIadd\fP
Adds a new disk to the guest.
Usage: '\fBiohyve\fP \fIadd\fP <name> <size> [\fIpool\fP]' where <name> is
the name of the guest, <size> is the size of the
virtual block device in '16G' format where the capital G
signifies gigabytes. If \fIpool\fP is specified, the disk gets
added on that \fIpool\fP
.TP
.B
\fIremove\fP
Removes a disk from the guest. Cannot be disk0.
Usage: '\fBiohyve\fP \fIremove\fP <name> <diskN>' where <name> is
the name of the guest, <diskN> is the disk you would
like to \fIremove\fP from the guest. See '\fBiohyve\fP \fIdisks\fP' for
a \fIlist\fP of \fIdisks\fP for a guest. If [\fB-f\fP] is supplied before the
<name>, there is no prompt to \fIremove\fP.
.TP
.B
\fIresize\fP
Resizes a disk. THIS CAN BREAK THINGS ON THE GUEST.
Usage: '\fBiohyve\fP \fIresize\fP <name> <diskN> <size>' where <name> is
the name of the guest, <diskN> is the disk you would
like to \fIremove\fP from the guest, and <size> is the size
of the virtual block device in '16G' format where the
capital G signifies gigabytes.
See '\fBiohyve\fP \fIdisks\fP' for a \fIlist\fP of \fIdisks\fP for a guest
.TP
.B
\fIdisks\fP
Lists the \fIdisks\fP attached to a guest.
Usage: '\fBiohyve\fP \fIdisks\fP <name>' where <name> is the name
of the guest operating system.
.TP
.B
\fIsnap\fP
Take a snapshot of a guest.
Usage: '\fBiohyve\fP \fIsnap\fP <name>@<\fIsnap\fP>' where <name> is the
name of the guest and <\fIsnap\fP> is what you would
like to name the snapshot.
.TP
.B
\fIroll\fP
Rollback guest to a snapshot.
Usage: '\fBiohyve\fP \fIroll\fP <name>@<\fIsnap\fP>' where <name> is the
name of the guest and <\fIsnap\fP> is what you would
like to name the snapshot.
.TP
.B
\fIclone\fP
Clone a guest. Note that this will \fIclone\fP all of the properties.
If you want to use the \fIclone\fP and the original guest at the
same time you will need to change the tap and nmdm properties
or use the \fB-r\fP option to have \fBiohyve\fP do this for you
Usage: '\fBiohyve\fP \fIclone\fP [\fB-r\fP] <name> <clonename>' where <name>
is the name of the guest and <clonename> is what you would
like to name the new \fIclone\fP.
.TP
.B
\fIexport\fP
Export a guest with all of it's properties and \fIdisks\fP to a
GZip'd tarball. Property file is in a ucl-type format.
Disks output to a raw file, allowing for other managers using
ahci-hd emulation to use them. Tarball is put in the guest
dataset ex: /\fBiohyve\fP/guestname/guestname.tar.gz
Usage: '\fBiohyve\fP \fIexport\fP <name>' where <name> is the name of the
guest.
.TP
.B
\fIsnaplist\fP
List all of the snapshots for all the guests. Does not show
snapshots of \fIdisks\fP (they are there, though).
.TP
.B
\fItaplist\fP
Lists all of the network taps taken by \fBiohyve\fP guests
This will \fIlist\fP taps that are not active as well.
.TP
.B
\fIactivetaps\fP
Lists all active taps in use.
.TP
.B
\fIconlist\fP
Lists all of the nullmodem consoles taken by \fBiohyve\fP guests.
This will \fIlist\fP taps that are not active as well.
.TP
.B
\fIconsole\fP
Consoles into a guest operating system. Utilizes \fBnmdm\fP(4) and
\fBcu\fP(1) to open a \fIconsole\fP on a guest operating system. Since
\fBbhyve\fP(8) does not emulate video, so we need to administer
the guests via a serial communication device. Since \fBiohyve\fP
uses \fBcu\fP(1), you will need to press the tilde (~) twice
then period (.) to exit the \fIconsole\fP.
(Think typing ~~. real fast to exit \fIconsole\fP)
If that fails to work, try pressing tilde (~) then press
Control + D (^D). Note that on some machines, you cannot
escape the \fIconsole\fP. See \fIconreset\fP below to escape all consoles.
Usage: '\fBiohyve\fP \fIconsole\fP <name>' where <name> is the name
of the guest operating system.
.TP
.B
\fIconreset\fP
Ends all \fIconsole\fP sessions for when things \fIget\fP weird.
.TP
.B
\fIhelp\fP
General usage \fIhelp\fP.
.SH EXAMPLES

Setup \fBiohyve\fP zpool named tank:
.PP
\fBiohyve\fP \fIsetup\fP \fIpool\fP=tank
.PP
Fetch FreeBSD \fIinstall\fP ISO for later:
.PP
\fBiohyve\fP \fIfetchiso\fP ftp://ftp.freebsd.org/\.\.\./10.2/FreeBSD\.\.\..iso
.PP
Create a new FreeBSD guest named bsdguest on \fIconsole\fP nmdm0 with an 8Gigabyte virtual HDD:
.PP
\fBiohyve\fP \fIcreate\fP bsdguest 8G
.PP
List ISO's:
.PP
\fBiohyve\fP \fIisolist\fP
.PP
Install the FreeBSD guest bsdguest:
.PP
\fBiohyve\fP \fIinstall\fP bsdguest FreeBSD-10.2-RELEASE-amd64-bootonly.iso
.PP
Console into the intallation:
.PP
\fBiohyve\fP \fIconsole\fP bsdguest
.PP
Once installation is done, exit \fIconsole\fP (~~.) and \fIdestroy\fP guest:
.PP
\fBiohyve\fP \fIdestroy\fP bsdguest
.PP
Now that the guest is installed, it can be started like usual:
.PP
\fBiohyve\fP \fIstart\fP bsdguest
.PP
Some guest os's can be gracefully stopped:
.PP
\fBiohyve\fP \fIstop\fP bsdguest
.PP
List all guests created with:
.PP
\fBiohyve\fP \fIlist\fP
.PP
List all guests that have resources allocated using:
.PP
\fBiohyve\fP vmmlist
.PP
List all runnng guests using:
.PP
\fBiohvye\fP running
.PP
You can change guest properties by using \fIset\fP:
.PP
\fBiohyve\fP \fIset\fP bsdguest ram=512M
\fBiohyve\fP \fIset\fP bsdguest cpu=1
\fBiohyve\fP \fIset\fP bsdguest tap=tap0
\fBiohyve\fP \fIset\fP bsdguest con=nmdm0
.PP
Get a spcific guest property:
.PP
\fBiohyve\fP \fIget\fP bsdguest ram
.PP
Get all guest properties:
.PP
\fBiohyve\fP \fIgetall\fP bsdguest
.PP
Install and run a Debian guest:
.PP
\fBiohyve\fP \fIcreate\fP debianvm 8G
\fBiohyve\fP \fIset\fP debianvm loader=grub-bhyve
\fBiohyve\fP \fIinstall\fP debianvm deb8.1-net.iso
\fBiohyve\fP \fIstart\fP debianvm
.PP
Take a snapshot of a guest:
.PP
\fBiohyve\fP \fIsnap\fP bsdguest@beforeupdate
\fBiohyve\fP \fIsnaplist\fP
\fBiohyve\fP \fIroll\fP bsdguest@beforeupdate
.PP
Make an independent \fIclone\fP of a guest:
.PP
\fBiohyve\fP \fIclone\fP bsdguest dolly
.SH AUTHOR
Trent -- @pr1ntf
.SH SEE ALSO
\fBbhyve\fP(8), \fBbhyveload\fP(8), \fBzfs\fP(8), \fBnmdm\fP(4),
\fBcu\fP(1), \fBif_bridge\fP(4), grub2-\fBbhyve\fP(8)