NAME

iohyve(8) - bhyve manager/launcher v0.7.9 "I Believe in You, You Can Do the Thing Edition"

SYNOPSIS

iohyve version
iohyve setup <pool=poolname> [kmod=0|1] [net=iface]
iohyve list [-l]
iohyve info [-vsdl]
iohyve isolist
iohyve fwlist
iohyve fetchiso <URL>
iohyve cpiso <path>
iohyve renameiso <ISO> <newname>
iohyve rmiso <ISO>
iohyve fetchfw <URL>
iohyve cpfw <path>
iohyve renamefw <firmware> <newname>
iohyve rmfw <firmware>
iohyve create <name> <size> [pool]
iohyve install <name> <ISO>
iohyve load <name>
iohyve boot <name> <ISO>
iohyve start <name> [-a | -s]
iohyve stop <name>
iohyve forcekill <name>
iohyve scram
iohyve destroy <name>
iohyve rename <name> <newname>
iohyve delete [-f] <name>
iohyve set <name> <property=value> ...
iohyve get <name> <prop>
iohyve rmprop [-f] <name> <property>
iohyve getall <name>
iohyve add <name> <size>
iohyve remove [-f] <name> <diskN>
iohyve resize <name> <diskN> <size>
iohyve disks <name>
iohyve snap <name>@<snap>
iohyve roll <name>@<snap>
iohyve rmsnap [-f] <name>@<snap>
iohyve clone [-r] <name> <clonename>
iohyve export <name>
iohyve snaplist
iohyve taplist
iohyve tapadd <name> [iface]
iohyve tapdel <name> <tap>
iohyve activetaps
iohyve conlist
iohyve console <name>
iohyve conreset
iohyve help
iohyve man

DESCRIPTION

The iohyve(8) shell script utilizes the FreeBSD hypervisor bhyve(8), zfs(8), and nmdm(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. iohyve(8) uses the virtio drivers built into the GENERIC kernel for virtualization.

OPTIONS

version: Prints the current running version of iohyve
setup: Installs required zfs datasets and kernel modules for iohyve. Usage: 'iohyve setup <pool=poolname> [kmod=0|1] [net=iface]' where <poolname> is the pool you want to install iohyve on, kmod=<0|1> is if you want iohyve to load or unload the kernel modules required by iohyve. 1 is load. net=<iface> will set up the network bridge to the specified interface. Multiple pools are supported, additional pools get mounted in /iohyve/poolname
list: Lists the name, status for VMM, active bhyve (Running), boot on start flag (rcboot), and description for each guest.

-l flag pipes the final output to less

info: Lists properties about the guests and their disks 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, pool, and the description. Use -l to pipe to less.

-v is for verbose which adds the fields: OS, Loader, Tap, and Con.

-s is for status which add the fields: VMM, Running, and rcboot.

-d is for description. Shows the guest description.

-l is for less and pipes the final output to less.

Order of flags is not important. The proper syntax is to use the flags contiguiously. So "-ld" is the correct way to display the base output plus description, and then have the output piped to less.

isolist: Lists the installed ISOs in the /iohyve/ISO directory.
fwlist: Lists the firmwares in the /iohyve/Firmware directory.
fetchiso: Fetches installation ISO or install image and creates a dataset for it. Usage: 'iohyve fetchiso <URL>' where <URL> is the HTTP or FTP URL to fetchiso from the internet.
cpiso: Copies installation ISO or install image from your host and creates a dataset for it. Usage: 'iohyve cpiso <path>' where <path> is the full path to ISO file on the host machine.
renameiso: Renames an ISO Usage: 'iohyve renameiso <ISO> <newname>' where <ISO> is the name of the ISO you would like to rename. <newname> is a new name.
rmiso: Removes installed ISO from /iohyve/ISO Usage: 'iohyve rmiso <ISO>' where <ISO> is the name of the ISO you would like to delete.
fetchfw: Fetches firmware and creates a dataset for it. Usage: 'iohyve fetchfw <URL>' where <URL> is the HTTP or FTP URL to fetch from the internet.
cpfw: Copies firmware from your host and creates a dataset for it. Usage: 'iohyve cpfw <path>' where <path> is the full path to firmware file on the host machine.
renamefw: Renames a Firmware Usage: 'iohyve renamefw <firmware> <newname>' where <firmware> is the name of the firmware you would like to rename. <newname> is a new name.
rmfw: Removes installed firmware from /iohyve/Firmware Usage: 'iohyve rmfw <firmware>' where <firmware> is the name of the firmware you would like to delete.
create: Creates new guest operating system. Usage: 'iohyve create <name> <size> [pool]' 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 pool, the first disk gets added on that pool.
install: Loads and boots into ISO for guest installation. Usage: 'iohyve install <name> <ISO>' where <name> is the name of the guest, and [ISO] is the name of the ISO you would like to boot from in the form of: 'instal.iso'
start: Starts the guest operating system. (Combines load & boot) Usage: 'iohyve start <name> [-s | -a]' where <name> is the name of the guest operating system. [-s] will cause the guest to be started once [-a] will cause the guest to always restart
stop: Gracefully stops guest operating system. Usage: 'iohyve stop <name>' where <name> is the name of the guest operating system.
forcekill: Forces the guest to stop. Runs kill -9 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 console that you do not have access to.
scram: Gracefully stop all bhyve guests. Does not destroy resources.
destroy: Destroys guest resources. Usage: 'iohyve destroy <name>' where <name> is the name of the guest operating system. Destroying a guest does not [delete] a guest from the host, it destroys the guest in VMM.
rename: Renames the guest Usage: 'iohyve rename <name> <newname>' where <name> is the name of the guest and <newname> is the new name.
delete: Deletes all data for the guest. Usage: 'iohyve delete <name>' where <name> is the name of the guest operating system. If [-f] is supplied before the <name>, there is no prompt to delete.
set: Sets ZFS properties for guests one at a time Usage: 'iohyve set <name> <property=value> ...' where <name> is the name of the guest operating system. See PROPERTIES for a list of properties you can set.
get: Gets ZFS properties for guests one at a time Usage: 'iohyve get <name> <prop>' where <name> is the name of the guest operating system. <prop> is the property you want to view. (See 'iohyve set' info)
rmprop: Removes a property from the guest Usage: 'iohyve rmprop <name> <property>' where <name> is the name of the guest operating system. <property> is the property you want removed. Use with caution. If [-f] is supplied before the <name>, there is no prompt to remove.
getall: Gets all the ZFS properties for a guest Usage: 'iohyve getall <name>' where <name> is the name of the guest operating system.
add: Adds a new disk to the guest. Usage: 'iohyve add <name> <size>' 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.
remove: Removes a disk from the guest. Cannot be disk0. Usage: 'iohyve remove <name> <diskN>' where <name> is the name of the guest, <diskN> is the disk you would like to remove from the guest. See 'iohyve disks' for a list of disks for a guest. If [-f] is supplied before the <name>, there is no prompt to remove.
resize: Resizes a disk. THIS CAN BREAK THINGS ON THE GUEST. Usage: 'iohyve resize <name> <diskN> <size>' where <name> is the name of the guest, <diskN> is the disk you would like to remove from the guest, and <size> is the size of the virtual block device in '16G' format where the capital G signifies gigabytes. See 'iohyve disks' for a list of disks for a guest
disks: Lists the disks attached to a guest. Usage: 'iohyve disks <name>' where <name> is the name of the guest operating system.
snap: Take a snapshot of a guest. Usage: 'iohyve snap <name>@<snap>' where <name> is the name of the guest and <snap> is what you would like to name the snapshot.
roll: Rollback guest to a snapshot. Usage: 'iohyve roll <name>@<snap>' where <name> is the name of the guest and <snap> is what you would like to name the snapshot.
rmsnap: Removes a snapshot of a guest Usage: 'iohyve rmsnap <name>@<snap>' where <name> is the name of the guest operating system. <snap> is the snapshot you want removed. Use with caution. If [-f] is supplied before the <name>, there is no prompt to remove.
clone: Clone a guest. Note that this will clone all of the properties. If you want to use the clone and the original guest at the same time you will need to change the tap and nmdm properties or use the -r option to have iohyve do this for you Usage: 'iohyve clone [-r] <name> <clonename>' where <name> is the name of the guest and <clonename> is what you would like to name the new clone.
export: Export a guest with all of it's properties and disks 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: /iohyve/guestname/guestname.tar.gz Usage: 'iohyve export <name>' where <name> is the name of the guest.
snaplist: List all of the snapshots for all the guests. Does not show snapshots of disks (they are there, though).
taplist: Lists all of the network taps taken by iohyve guests This will list taps that are not active as well.
tapadd: Adds new network tap interface to the guest <name>. If [iface] is set, then new created network tap is assigned to the bridge, which contains network interface [iface]. Otherwise the default network interface is used (network interface used during the setup)
tapdel: Remove network tap interface <tap> from the quest <name>.
activetaps: Lists all active taps in use.
conlist: Lists all of the nullmodem consoles taken by iohyve guests. This will list taps that are not active as well.
console: Consoles into a guest operating system. Utilizes nmdm(4) and cu(1) to open a console on a guest operating system. Since bhyve(8) does not emulate video, so we need to administer the guests via a serial communication device. Since iohyve uses cu(1), you will need to press the tilde (~) twice then period (.) to exit the console. (Think typing ~~. real fast to exit console) If that fails to work, try pressing tilde (~) then press Control + D (^D). Note that on some machines, you cannot escape the console. See conreset below to escape all consoles. Usage: 'iohyve console <name>' where <name> is the name of the guest operating system.
conreset: Ends all console sessions for when things get weird.
help: General usage help.

PROPERTIES

ram=N: Defaults to 512M (Use M for megabytes, G for gigabytes)
cpu=N: Number of cpu cores. Defaults to 1.
con=nmdmN: Where to attach null modem console (ex: nmdm4)
tap=tap[N](,tap[N]): (tap device for virtio-net) [n] is a generic number to specify the tap interface to use. Specify a list of taps separated by comma for multiple tap interfaces. Single tap: iohyve set [name] tap=tap0 Multiple tap : iohyve set [name] tap=tap0,tap1,tap2,tap3
size=N: Size of block device
mac_tap[N]=[MAC Addr]: [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. iohyve does not check for a valid MAC address, so double check the property.
sectorsize=[N]: [N] is the sectorsize in kilobyte for the disk attached to the guest. Only used for uefi guests. See "sectorsize" in bhyve(8) Examples: "sectorsize=512"
pcidev:[n]=<spec>: Generic way to add 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 -s argument without the pcislot or function argument. PCI slot numbers are assigned automatically by iohyve. Examples: "pcidev:1=passthru,2/0/0" "pcidev:2=ahci-hd,/some/place/disk.img"
bargs=[bargs_text]: You can specify differnt bhyve arguments using bargs. Separate each argument with and underscore (_) (ex: bargs=-A_-H_-P will use the -A, -H, and -P flags when launching bhyve)
description=[text]: Give guest a description. Place text between two double quotes ("text") (ex: description="This is my string I use to describe this guest.")
template=[YES|NO]: Set to YES to stop iohyve from starting, renaming, and deleting a guest.
boot=[0|1]: Set to "1" to start guest on boot if using rcboot.
bhyve_path=[path]: Set the path to a custom binary of bhyve if it's not in /usr/sbin/bhyve Defaults to /usr/sbin/bhyve
UTC=[YES|NO]: Set to "YES" to set the bhyve clock to UTC. On by default.
loader=[loadername]: Default is bhyveload. Use grub-bhyve to boot using grub2-bhyve if installed. Set to uefi to use UEFI booting. (Requires fw to be set)
fw=[firmware]: The firmware to use when booting via UEFI. See cpfw and fetchfw for more info on adding firmware to iohyve. If you installed the systutils/bhyve-uefi package or port, you must run iohyve cpfw /usr/local/share/uefi-firmware/BHYVE_UEFI.fd and set fw=BHYVE_UEFI.fd (view installed fw with iohyve fwlist).
os=[osname]: If using the grub-bhyve loader you can specify an os type to automatically boot some OS's. Choices are openbsd57, openbsd58, openbsd59, openbsd60, openbsd61, netbsd, debian (non-LVM), d8lvm (LVM installs), centos6, centos7(non-XFS), ubuntu (LVM installs, non-LVM use debian), arch and custom. Choosing custom means your device.map and grub.cfg are in your guest dataset on the host (ex: /iohyve/bsdguest/device.map and /iohyve/bsdguest/grub.cfg).
vnc=[YES|NO]: Change to YES to use the bhyve fbuf UEFI firmware which uses VNC over TCP. Special UEFI firmware is required for this, and can be found in ports.
vnc_wait=[YES|NO]: Tells bhyve not to boot the guest until a connections is established via VNC.
vnc_tablet[YES|NO]: Tells bhyve to use the XHCI Tablet Touch Interface that makes the mouse behave better on some OS's. Does not work on all OS's.
vnc_ip=[ip addr]: IP Address to bind the TCP VNC server to. 127.0.0.1 by default.
vnc_port[N]: TCP Port to bind the VNC server to.
vnc_w=[N]: Width of console (See Below)
vnc_h=[N]: Height of console (See Below)
Video Modes: Currently, bhyve only support the following video modes (w x h) 1920 x 1200, 1920 x 1080, 1600 x 1200, 1600 x 900, 1280 x 1024, 1280 x 720, 1024 x 768, 800 x 600, and 640 x 480

EXAMPLES

Setup iohyve zpool named tank:

iohyve setup pool=tank

Fetch FreeBSD install ISO for later:

iohyve fetchiso ftp://ftp.freebsd.org/.../10.2/FreeBSD....iso

Create a new FreeBSD guest named bsdguest on console nmdm0 with an 8Gigabyte virtual HDD:

iohyve create bsdguest 8G

List ISO's:

iohyve isolist

Install the FreeBSD guest bsdguest:

iohyve install bsdguest FreeBSD-10.2-RELEASE-amd64-bootonly.iso

Console into the intallation:

iohyve console bsdguest

Once installation is done, exit console (~~.) and destroy guest:

iohyve destroy bsdguest

Now that the guest is installed, it can be started like usual:

iohyve start bsdguest

Some guest os's can be gracefully stopped:

iohyve stop bsdguest

List all guests created with:

iohyve list

You can change guest properties by using set:

iohyve set bsdguest description="FreeBSD is awesome"

You can also set multiple properties at once:

iohyve set bsdguest ram=512M cpu=1 boot=1

Get a specific guest property:

iohyve get bsdguest ram

Get all guest properties:

iohyve getall bsdguest

Install an OpenBSD guest:

iohyve set obsdguest loader=grub-bhyve os=openbsd59

iohyve install obsdguest install59.iso

iohyve console obsdguest

Take a snapshot of a guest:

iohyve snap bsdguest@beforeupdate

Roll back to a previous snapshot:

iohyve roll bsdguest@beforeupdate

List all snapshots in iohyve:

iohyve snaplist

Make an independent clone of a guest:

iohyve clone bsdguest dolly

Make a guest a template so you cannot be started, renamed, or deleted:

iohyve set bsdguest template=YES

AUTHOR

Trent -- @pr1ntf