iohyve.8.txt

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

SEE ALSO
bhyve(8), bhyveload(8), zfs(8), nmdm(4),
cu(1), if_bridge(4), grub2-bhyve(8)