iohyve.8.txt

NAME
iohyve(8) - bhyve manager/launcher v0.7.3 "Bear in a Datacenter Edition"

SYNOPSIS
iohyve version
iohyve setup pool=[poolname] kmod=[0/1] net=[interface]
iohyve list
iohyve info [-d]
iohyve isolist
iohyve fwlist
iohyve fetch [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 [name]
iohyve set [name] [prop1=value] [prop2=value]...
iohyve get [name] [prop]
iohyve rmpci [name] [pcidev:N]
iohyve getall [name]
iohyve add [name] [size] [[pool]]
iohyve remove [name] [diskN]
iohyve resize [name] [diskN] [size]
iohyve disks [name]
iohyve snap [name]@[snapshotname]
iohyve roll [name]@[snapshotname]
iohyve clone [-c | -r] [name] [clonename]
iohyve snaplist
iohyve taplist
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 zfs dataset directorys for iohyve.

info		Lists all the guests along with their RAM, CPU, Size,
		OS, Loader, and Description (if -d is passed)

isolist		List Lists the installed ISOs in the /iohyve/ISO directory.

fwlist		Lists the firmwares in the /iohyve/Firmware directory.

fetch		Fetches installation ISO or install image and creates a
		dataset for it.
		Usage: 'iohyve fetch [URL]' where [URL] is the HTTP or FTP URL to
		fetch 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'

load		Loads the guest operating system bootloader and resources.
		Usage: 'iohyve load [name] [ISO]'
		where [name]is the name of the guest operating system.
		[bootimg] is the path to the boot medium

boot		Boots the guest into the operating system. 'iohyve run' needs
		to be run before this is done.
		Usage: 'iohyve boot [name] [runmode] [pci]'
		where [name]is the name of the guest operating system.
		[runmode] describes how to start the guest:
		0 = start only once
		1 = regular persist
		Stop if the guest is powering off
		2 = always persist
		Always restart the guest
		[pci] is a space separated list of pci devices
		based on slot-less bhyve -s commands.
		Example:
		"ahci-hd,/path/disk.img virtio-net,tap0"
		Note: hostbridge and lpc are automatically
		added

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.

set		Sets ZFS properties for guests one at a time
		Usage: 'iohyve set [name] [prop1=value] [prop2=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 console)
		tap=tap0 (tap device for virtio-net)
		size=size of block device
		mac=[MAC Address]
			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.
		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"

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)

rmpci		Removes a pcidev from the guest
		Usage: 'iohyve rmpci [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'

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] [[pool]]' 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 pool is specified, the disk gets
		added on that pool

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

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]@[snapshot]' where [name] is the
		name of the guest and [snapshot] is what you would
		like to name the snapshot.

roll		Rollback guest to a snapshot.
		Usage: 'iohyve roll [name]@[snapshot]' where [name] is the
		name of the guest and [snapshot] is what you would
		like to name the snapshot.

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 [-c | -r] [name] [clonename]' where [name]
		is the name of the guest and [clonename] is what you would
		like to name the new clone.

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.

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.

EXAMPLES

Setup iohyve zpool named tank:

iohyve setup pool=tank

Fetch FreeBSD install ISO for later:

iohyve fetch 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

List all guests that have resources allocated using:

iohyve vmmlist

List all runnng guests using:

iohvye running

You can change guest properties by using set:

iohyve set bsdguest ram=512M
iohyve set bsdguest cpu=1
iohyve set bsdguest tap=tap0
iohyve set bsdguest con=nmdm0

Get a spcific guest property:

iohyve get bsdguest ram

Get all guest properties:

iohyve getall bsdguest

Install and run a Debian guest:

iohyve create debianvm 8G
iohyve set debianvm loader=grub-bhyve
iohyve install debianvm deb8.1-net.iso
iohyve start debianvm

Take a snapshot of a guest:

iohyve snap bsdguest@beforeupdate
iohyve snaplist
iohyve roll bsdguest@beforeupdate

Make an independent clone of a guest:

iohyve clone bsdguest dolly

AUTHOR
Trent -- @pr1ntf

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