FreeBSD Manual Pages
iohyve(8) FreeBSD System Manager's Manual iohyve(8) 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 sta- tus, 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 cre- ates 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 sys- tem. <property> is the property you want removed. Use with cau- tion. 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 signi- fies 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 sup- plied before the <name>, there is no prompt to remove. resize Resizes a disk. THIS CAN BREAK THINGS ON THE GUEST. Usage: 'io- hyve 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 'io- hyve 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 cau- tion. 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: /io- hyve/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 ran- dom 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 au- tomatically 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/bs- dguest/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 estab- lished 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 8Gi- gabyte 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) 27 June 2017 iohyve(8)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PROPERTIES | EXAMPLES | AUTHOR | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=iohyve&sektion=8&manpath=FreeBSD+Ports+14.3.quarterly>