iohyve.8

.\" Text automatically generated by txt2man
.TH iohyve 8 "02 February 2016" "" "FreeBSD System Manager's Manual"
.SH NAME
\fBiohyve(8) \fP- bhyve manager/launcher v0.7.3 "Bear in a Datacenter Edition"
\fB
.SH SYNOPSIS
.nf
.fam C
\fBiohyve\fP \fIversion\fP
\fBiohyve\fP \fIsetup\fP pool=[poolname] kmod=[0/1] net=[interface]
\fBiohyve\fP \fIlist\fP
\fBiohyve\fP \fIinfo\fP [\fB-d\fP]
\fBiohyve\fP \fIisolist\fP
\fBiohyve\fP \fIfwlist\fP
\fBiohyve\fP \fIfetch\fP [\fIURL\fP]
\fBiohyve\fP \fIcpiso\fP [\fIpath\fP]
\fBiohyve\fP \fIrenameiso\fP [\fIISO\fP] [\fInewname\fP]
\fBiohyve\fP \fIrmiso\fP [\fIISO\fP]
\fBiohyve\fP \fIfetchfw\fP [\fIURL\fP]
\fBiohyve\fP \fIcpfw\fP [\fIpath\fP]
\fBiohyve\fP \fIrenamefw\fP [\fIfirmware\fP] [\fInewname\fP]
\fBiohyve\fP \fIrmfw\fP [\fIfirmware\fP]
\fBiohyve\fP \fIcreate\fP [\fIname\fP] [\fIsize\fP] [[\fIpool\fP]]
\fBiohyve\fP \fIinstall\fP [\fIname\fP] [\fIISO\fP]
\fBiohyve\fP \fIload\fP [\fIname\fP]
\fBiohyve\fP \fIboot\fP [\fIname\fP] [\fIISO\fP]
\fBiohyve\fP \fIstart\fP [\fIname\fP] [\fB-a\fP | \fB-s\fP]
\fBiohyve\fP \fIstop\fP [\fIname\fP]
\fBiohyve\fP \fIforcekill\fP [\fIname\fP]
\fBiohyve\fP \fIscram\fP
\fBiohyve\fP \fIdestroy\fP [\fIname\fP]
\fBiohyve\fP \fIrename\fP [\fIname\fP] [\fInewname\fP]
\fBiohyve\fP \fIdelete\fP [\fIname\fP]
\fBiohyve\fP \fIset\fP [\fIname\fP] [\fIprop1=value\fP] [prop2=value]\.\.\.
\fBiohyve\fP \fIget\fP [\fIname\fP] [\fIprop\fP]
\fBiohyve\fP \fIrmpci\fP [\fIname\fP] [\fIpcidev:N\fP]
\fBiohyve\fP \fIgetall\fP [\fIname\fP]
\fBiohyve\fP \fIadd\fP [\fIname\fP] [\fIsize\fP] [[\fIpool\fP]]
\fBiohyve\fP \fIremove\fP [\fIname\fP] [\fIdiskN\fP]
\fBiohyve\fP \fIresize\fP [\fIname\fP] [\fIdiskN\fP] [\fIsize\fP]
\fBiohyve\fP \fIdisks\fP [\fIname\fP]
\fBiohyve\fP \fIsnap\fP [\fIname\fP]@[snapshotname]
\fBiohyve\fP \fIroll\fP [\fIname\fP]@[snapshotname]
\fBiohyve\fP \fIclone\fP [\fB-c\fP | \fB-r\fP] [\fIname\fP] [\fIclonename\fP]
\fBiohyve\fP \fIsnaplist\fP
\fBiohyve\fP \fItaplist\fP
\fBiohyve\fP \fIactivetaps\fP
\fBiohyve\fP \fIconlist\fP
\fBiohyve\fP \fIconsole\fP [\fIname\fP]
\fBiohyve\fP \fIconreset\fP
\fBiohyve\fP \fIhelp\fP
\fBiohyve\fP \fIman\fP

.fam T
.fi
.fam T
.fi
.SH DESCRIPTION
The \fBiohyve\fP(8) 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=poolname\fP \fIkmod=0/1\fP net=[iface]' 
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 zfs dataset directorys for \fBiohyve\fP.
.TP
.B
\fIinfo\fP
Lists all the guests along with their RAM, CPU, Size,
OS, Loader, and Description (if \fB-d\fP is passed)
.TP
.B
\fIisolist\fP
List Lists the installed ISOs in the /\fBiohyve\fP/\fIISO\fP directory.
.TP
.B
\fIfwlist\fP
Lists the firmwares in the /\fBiohyve\fP/Firmware directory.
.TP
.B
\fIfetch\fP
Fetches installation \fIISO\fP or \fIinstall\fP image and creates a
dataset for it.
Usage: '\fBiohyve\fP \fIfetch\fP [\fIURL\fP]' where [\fIURL\fP] is the HTTP or FTP \fIURL\fP to
\fIfetch\fP from the internet.
.TP
.B
\fIcpiso\fP
Copies installation \fIISO\fP or \fIinstall\fP image from your host and
creates a dataset for it.
Usage: '\fBiohyve\fP \fIcpiso\fP [\fIpath\fP]' where [\fIpath\fP] is the full \fIpath\fP to
\fIISO\fP file on the host machine.
.TP
.B
\fIrenameiso\fP
Renames an \fIISO\fP
Usage: '\fBiohyve\fP \fIrenameiso\fP [\fIISO\fP] [\fInewname\fP]' where [\fIISO\fP] is the
\fIname\fP of the \fIISO\fP you would like to \fIrename\fP. [\fInewname\fP]
is a new \fIname\fP.
.TP
.B
\fIrmiso\fP
Removes installed \fIISO\fP from /\fBiohyve\fP/\fIISO\fP
Usage: '\fBiohyve\fP \fIrmiso\fP [\fIISO\fP]' where [\fIISO\fP] is the \fIname\fP of the \fIISO\fP
you would like to \fIdelete\fP.
.TP
.B
\fIfetchfw\fP
Fetches \fIfirmware\fP and creates a dataset for it.
Usage: '\fBiohyve\fP \fIfetchfw\fP [\fIURL\fP]' where [\fIURL\fP] is the HTTP or FTP \fIURL\fP to
\fIfetch\fP from the internet.
.TP
.B
\fIcpfw\fP
Copies \fIfirmware\fP from your host and creates a dataset for it.
Usage: '\fBiohyve\fP \fIcpfw\fP [\fIpath\fP]' where [\fIpath\fP] is the full \fIpath\fP to
\fIfirmware\fP file on the host machine.
.TP
.B
\fIrenamefw\fP
Renames a Firmware
Usage: '\fBiohyve\fP \fIrenamefw\fP [\fIfirmware\fP] [\fInewname\fP]' where [\fIfirmware\fP]
is the \fIname\fP of the \fIfirmware\fP you would like to \fIrename\fP.
[\fInewname\fP] is a new \fIname\fP.
.TP
.B
\fIrmfw\fP
Removes installed \fIfirmware\fP from /\fBiohyve\fP/Firmware
Usage: '\fBiohyve\fP \fIrmfw\fP [\fIfirmware\fP]' where [\fIfirmware\fP] is the \fIname\fP of
the \fIfirmware\fP you would like to \fIdelete\fP.
.TP
.B
\fIcreate\fP
Creates new guest operating system.
Usage: '\fBiohyve\fP \fIcreate\fP [\fIname\fP] [\fIsize\fP] [[\fIpool\fP]]' where [\fIname\fP] is
the \fIname\fP you would like to use, [\fIsize\fP] is the \fIsize\fP 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 \fIISO\fP for guest installation.
Usage: '\fBiohyve\fP \fIinstall\fP [\fIname\fP] [\fIISO\fP]' where [\fIname\fP] is the \fIname\fP
of the guest, and [\fIISO\fP] is the \fIname\fP of the \fIISO\fP you would
like to \fIboot\fP from in the form of: 'instal.iso'
.TP
.B
\fIload\fP
Loads the guest operating system bootloader and resources.
Usage: '\fBiohyve\fP \fIload\fP [\fIname\fP] [\fIISO\fP]'
where [\fIname\fP]is the \fIname\fP of the guest operating system.
[bootimg] is the \fIpath\fP 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 [\fIname\fP] [runmode] [pci]'
where [\fIname\fP]is the \fIname\fP 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,/\fIpath\fP/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 [\fIname\fP] [\fB-s\fP | \fB-a\fP]'
where [\fIname\fP] is the \fIname\fP 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 [\fIname\fP]' where [\fIname\fP] is the \fIname\fP
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 [\fIname\fP]' where [\fIname\fP] is the \fIname\fP
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 [\fIname\fP] [\fInewname\fP]' where [\fIname\fP] is the
\fIname\fP of the guest and [\fInewname\fP] is the new \fIname\fP.
.TP
.B
\fIdelete\fP
Deletes all data for the guest.
Usage: '\fBiohyve\fP \fIdelete\fP [\fIname\fP]' where [\fIname\fP] is the \fIname\fP
of the guest operating system.
.TP
.B
\fIset\fP
Sets ZFS properties for guests one at a time
Usage: '\fBiohyve\fP \fIset\fP [\fIname\fP] [\fIprop1=value\fP] [prop2=value]\.\.\.' where
[\fIname\fP] is the \fIname\fP 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=tap0 (tap device for virtio-net)
\fIsize\fP=\fIsize\fP of block device
mac=[MAC Address]
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 [\fIname\fP] [\fIprop\fP]' where [\fIname\fP] is the \fIname\fP
of the guest operating system. [\fIprop\fP] 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 [\fIname\fP] [\fIpcidev:N\fP]' where [\fIname\fP] is the \fIname\fP
of the guest operating system. [\fIpcidev:N\fP] is the PCI
device you want removed. Ex: 'pcidev:3'
.TP
.B
\fIgetall\fP
Gets all the ZFS properties for a guest
Usage: '\fBiohyve\fP \fIgetall\fP [\fIname\fP]' where [\fIname\fP] is the \fIname\fP
of the guest operating system.
.TP
.B
\fIadd\fP
Adds a new disk to the guest.
Usage: '\fBiohyve\fP \fIadd\fP [\fIname\fP] [\fIsize\fP] [[\fIpool\fP]]' where [\fIname\fP] is
the \fIname\fP of the guest, [\fIsize\fP] is the \fIsize\fP 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 [\fIname\fP] [\fIdiskN\fP]' where [\fIname\fP] is
the \fIname\fP of the guest, [\fIdiskN\fP] 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
.TP
.B
\fIresize\fP
Resizes a disk. THIS CAN BREAK THINGS ON THE GUEST.
Usage: '\fBiohyve\fP \fIresize\fP [\fIname\fP] [\fIdiskN\fP] [\fIsize\fP]' where [\fIname\fP] is
the \fIname\fP of the guest, [\fIdiskN\fP] is the disk you would
like to \fIremove\fP from the guest, and [\fIsize\fP] is the \fIsize\fP
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 [\fIname\fP]' where [\fIname\fP] is the \fIname\fP
of the guest operating system.
.TP
.B
\fIsnap\fP
Take a snapshot of a guest.
Usage: '\fBiohyve\fP \fIsnap\fP [\fIname\fP]@[snapshot]' where [\fIname\fP] is the
\fIname\fP of the guest and [snapshot] is what you would
like to \fIname\fP the snapshot.
.TP
.B
\fIroll\fP
Rollback guest to a snapshot.
Usage: '\fBiohyve\fP \fIroll\fP [\fIname\fP]@[snapshot]' where [\fIname\fP] is the
\fIname\fP of the guest and [snapshot] is what you would
like to \fIname\fP 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-c\fP | \fB-r\fP] [\fIname\fP] [\fIclonename\fP]' where [\fIname\fP]
is the \fIname\fP of the guest and [\fIclonename\fP] is what you would
like to \fIname\fP the new \fIclone\fP.
.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 [\fIname\fP]' where [\fIname\fP] is the \fIname\fP
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 \fIISO\fP for later:
.PP
\fBiohyve\fP \fIfetch\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 \fIISO\fP'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
iohvye 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)