3.6. iohyve

The iohyve class is used to manage virtual machines (VMs) running in the bhyve type 2 hypervisor.

Every iohyve class request contains the following parameters:

Parameter Value Description
id   Any unique value for the request, including a hash, checksum, or uuid.
name iohyve  
namespace sysadm  
action   Actions include “adddisk”, “create”, “delete”, “deletedisk”, “fetchiso”, “getprops”, “install”, “issetup”, “listdisks”, “listisos”, “listvms”, “renameiso”, “resizedisk”, “rmiso”, “setprop”, “setup”, “start”, “stop”, and “version”

The rest of this section provides examples of the available actions for each type of request, along with their responses.

3.6.1. List VMs

The “listvms” action lists information about currently installed VMs. For each VM, the response includes the VM’s name, description, whether or not it is scheduled to start when the host system boots, whether or not it is currently running, and whether or not the VM is currently loaded into memory.

REST Request

PUT /sysadm/iohyve
{
  "action" : "listvms"
}

REST Response

{
   "args": {
       "listvms": {
           "testguest": {
               "description": "February 1, 2016 at 03:11:57 PM EST",
               "rcboot": "NO",
               "running": "NO",
               "vmm": "YES"
           }
       }
   }
}

WebSocket Request

{
  "namespace" : "sysadm",
  "args" : {
     "action" : "listvms"
  },
  "name" : "iohyve",
  "id" : "fooid"
}

WebSocket Response

{
 "args": {
   "listvms": {
     "testguest": {
       "description": "February 1, 2016 at 03:11:57 PM EST",
       "rcboot": "NO",
       "running": "NO",
       "vmm": "YES"
     }
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.2. Fetch ISO

The “fetchiso” action is used to retrieve the installation ISO. It is used with the “url” argument which contains the ISO address beginning with http://, ftp://, or file://.

REST Request

PUT /sysadm/iohyve
{
  "url" : "ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/amd64/ISO-IMAGES/10.1/FreeBSD-10.1-RELEASE-amd64-disc1.iso",
  "action" : "fetchiso"
}

WebSocket Request

{
  "namespace" : "sysadm",
  "name" : "iohyve",
  "args" : {
     "url" : "ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/amd64/ISO-IMAGES/10.1/FreeBSD-10.1-RELEASE-amd64-disc1.iso",
     "action" : "fetchiso"
  },
  "id" : "fooid"
}

Response

{
 "args": {
   "fetchiso": {
     "command": "iohyve fetch ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/amd64/ISO-IMAGES/10.1/FreeBSD-10.1-RELEASE-amd64-disc1.iso",
     "comment": "Task Queued",
     "queueid": "{b3a8b980-a564-4ff8-86a2-1971bd4f58d1}"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

Dispatcher Events System Reply

{
 "namespace" : "events",
 "name" : "dispatcher",
 "id" : "none",
 "args" : {
   "event_system" : "sysadm/iohyve",
   "state" : "finished",
   "filename" : "<filename>",
   "percent_done" : "<number>%",
   "download_rate" : "<rate>",
   "process_details" : {
     "time_finished" : "<ISO 8601 time date string>",
     "cmd_list" : ["<command 1>", "<command 2>"],
     "return_codes/<command 1>" : "<code 1>",
     "return_codes/<command 2>" : "<code 2>",
     "process_id" : "<random>",
     "state" : "finished"
     }
  }
}

3.6.3. List ISOs

The “listisos” action lists all the known ISO files which iohyve can use.

REST Request

PUT /sysadm/iohyve
{
  "action" : "listisos"
}

WebSocket Request

{
  "name" : "iohyve",
  "namespace" : "sysadm",
  "id" : "fooid",
  "args" : {
     "action" : "listisos"
  }
}

Response

{
 "args": {
   "listisos": [
     "TRUEOS10.2-RELEASE-08-19-2015-x64-netinstall.iso"
   ]
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.4. Rename ISO

The “renameiso” action is used to to rename an existing ISO file on disk. Specify the existing name with “source” and the new name with “target”.

REST Request

PUT /sysadm/iohyve
{
  "source" : "test.iso",
  "target" : "102.iso",
  "action" : "renameiso"
}

WebSocket Request

{
  "args" : {
     "target" : "102.iso",
     "source" : "test.iso",
     "action" : "renameiso"
  },
  "id" : "fooid",
  "name" : "iohyve",
  "namespace" : "sysadm"
}

Response

{
 "args": {
   "renameiso": {
     "source": "test.iso",
     "target": "102.iso"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.5. Remove ISO

The “rmiso” action is used to to remove an existing ISO file from disk. Specify the ISO’s name as the “target”.

REST Request

PUT /sysadm/iohyve
{
  "action" : "rmiso",
  "target" : "FreeBSD-10.2-RELEASE-amd64-bootonly.iso"
}

WebSocket Request

{
  "id" : "fooid",
  "name" : "iohyve",
  "args" : {
     "target" : "FreeBSD-10.2-RELEASE-amd64-bootonly.iso",
     "action" : "rmiso"
  },
  "namespace" : "sysadm"
}

Response

{
 "args": {
   "rmiso": {
     "target": "FreeBSD-10.2-RELEASE-amd64-bootonly.iso"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.6. Setup iohyve

The “setup” action performs the initial setup of iohyve. It is mandatory to specify the FreeBSD device name of the “nic” and the ZFS “pool” to use.

REST Request

PUT /sysadm/iohyve
{
  "nic" : "re0",
  "pool" : "tank",
  "action" : "setup"
}

WebSocket Request

{
  "id" : "fooid",
  "name" : "iohyve",
  "args" : {
     "pool" : "tank",
     "nic" : "re0",
     "action" : "setup"
  },
  "namespace" : "sysadm"
}

Response

{
 "args": {
   "setup": {
     "nic": "re0",
     "pool": "tank"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.7. Determine iohyve Setup

The “issetup” action queries if iohyve has been setup and returns either “true” or “false”.

REST Request

PUT /sysadm/iohyve
{
  "action" : "issetup"
}

WebSocket Request

{
  "id" : "fooid",
  "namespace" : "sysadm",
  "args" : {
     "action" : "issetup"
  },
  "name" : "iohyve"
}

Response

{
 "args": {
   "issetup": {
     "setup": "true"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.8. Create Guest

The “create” action creates a new iohyve guest of the specified “name” and “size”.

REST Request

PUT /sysadm/iohyve
{
  "action" : "create",
  "name" : "bsdguest",
  "size" : "10G"
}

WebSocket Request

{
  "name" : "iohyve",
  "namespace" : "sysadm",
  "id" : "fooid",
  "args" : {
     "name" : "bsdguest",
     "action" : "create",
     "size" : "10G"
  }
}

Response

{
 "args": {
   "create": {
     "name": "bsdguest",
     "size": "10G"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.9. Install Guest

The “install” action starts the iohyve installation of the specified guest from the specified ISO. This action only boots the VM with the ISO; to do the actual installation, run iohyve console <name> from the system.

REST Request

PUT /sysadm/iohyve
{
  "name" : "bsdguest",
  "iso" : "FreeBSD-10.2-RELEASE-amd64-disc1.iso",
  "action" : "install"
}

WebSocket Request

{
  "namespace" : "sysadm",
  "name" : "iohyve",
  "id" : "fooid",
  "args" : {
     "action" : "install",
     "iso" : "FreeBSD-10.2-RELEASE-amd64-disc1.iso",
     "name" : "bsdguest"
  }
}

Response

{
 "args": {
   "install": {
     "iso": "FreeBSD-10.2-RELEASE-amd64-disc1.iso",
     "name": "bsdguest"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.10. Start VM

The “start” action starts the specified VM.

REST Request

PUT /sysadm/iohyve
{
  "action" : "start",
  "name" : "bsdguest"
}

WebSocket Request

{
  "name" : "iohyve",
  "id" : "fooid",
  "args" : {
     "action" : "start",
     "name" : "bsdguest"
  },
  "namespace" : "sysadm"
}

Response

{
 "args": {
   "start": {
     "name": "bsdguest"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.11. Stop VM

The “stop” action stops the specified VM.

REST Request

PUT /sysadm/iohyve
{
  "action" : "stop",
  "name" : "bsdguest"
}

WebSocket Request

{
  "id" : "fooid",
  "args" : {
     "action" : "stop",
     "name" : "bsdguest"
  },
  "name" : "iohyve",
  "namespace" : "sysadm"
}

Response

{
 "args": {
   "stop": {
     "name": "bsdguest"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.12. Delete a VM

The “delete” action deletes the specified iohyve guest.

REST Request

PUT /sysadm/iohyve
{
  "action" : "delete",
  "name" : "bsdguest"
}

WebSocket Request

{
  "namespace" : "sysadm",
  "id" : "fooid",
  "args" : {
     "action" : "delete",
     "name" : "bsdguest"
  },
  "name" : "iohyve"
}

Response

{
 "args": {
   "delete": {
     "name": "bsdguest"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.13. Add a Disk

The “adddisk” action adds and creates a disk for a VM.

REST Request

PUT /sysadm/iohyve
{
  "name" : "bsdguest",
  "action" : "adddisk",
  "size" : "10G"
}

WebSocket Request

{
  "args" : {
     "size" : "10G",
     "name" : "bsdguest",
     "action" : "adddisk"
  },
  "id" : "fooid",
  "namespace" : "sysadm",
  "name" : "iohyve"
}

Response

{
 "args": {
   "adddisk": {
     "bsdguest": {
       "size": "10G"
     }
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.14. List Disks

The “listdisks” action lists the disks connected to the specified VM.

REST Request

PUT /sysadm/iohyve
{
  "name" : "bsdguest",
  "action" : "listdisks"
}

WebSocket Request

{
  "args" : {
     "action" : "listdisks",
     "name" : "bsdguest"
  },
  "id" : "fooid",
  "namespace" : "sysadm",
  "name" : "iohyve"
}

Response

{
 "args": {
   "listdisks": {
     "disk0": "10G"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.15. Resize a Disk

The “resizedisk” action increases the specified disk in the specified VM. The new specified size must be larger than the current size.

REST Request

PUT /sysadm/iohyve
{
  "disk" : "disk0",
  "name" : "bsdguest",
  "action" : "resizedisk",
  "size" : "20G"
}

WebSocket Request

{
  "name" : "iohyve",
  "id" : "fooid",
  "args" : {
     "size" : "20G",
     "action" : "resizedisk",
     "disk" : "disk0",
     "name" : "bsdguest"
  },
  "namespace" : "sysadm"
}

Response

{
 "args": {
   "resizedisk": {
     "disk": "disk0",
     "name": "bsdguest",
     "size": "20G"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.16. Delete a Disk

The “deletedisk” action removes the specified disk from the specified VM.

REST Request

PUT /sysadm/iohyve
{
  "disk" : "disk1",
  "name" : "bsdguest",
  "action" : "deletedisk"
}

WebSocket Request

{
  "namespace" : "sysadm",
  "id" : "fooid",
  "name" : "iohyve",
  "args" : {
     "name" : "bsdguest",
     "action" : "deletedisk",
     "disk" : "disk1"
  }
}

Response

{
 "args": {
   "deletedisk": {
     "disk": "disk1",
     "name": "bsdguest"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.17. List Version

The “version” action displays the iohyve version.

REST Request

PUT /sysadm/iohyve
{
  "action" : "version"
}

WebSocket Request

{
  "namespace" : "sysadm",
  "args" : {
     "action" : "version"
  },
  "id" : "fooid",
  "name" : "iohyve"
}

Response

{
 "args": {
   "version": {
     "version": "iohyve v0.7.3 2016/01/08 Bear in a Datacenter Edition"
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.18. List Guest Properties

The “getprops” action lists the properties for the specified guest.

REST Request

PUT /sysadm/iohyve
{
  "action" : "getprops",
  "name" : "bsdguest"
}

WebSocket Request

{
  "id" : "fooid",
  "namespace" : "sysadm",
  "args" : {
     "name" : "bsdguest",
     "action" : "getprops"
  },
  "name" : "iohyve"
}

Response

{
 "args": {
   "getprops": {
     "bsdguest": {
       "autogrub": "\\n",
       "bargs": "-A_-H_-P",
       "boot": "0",
       "con": "nmdm0",
       "cpu": "1",
       "description": "Tue",
       "install": "no",
       "loader": "bhyveload",
       "name": "bsdguest",
       "os": "default",
       "persist": "1",
       "ram": "256M",
       "size": "10G",
       "tap": "tap0"
     }
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}

3.6.19. Set Guest Properties

The “setprop” action can be used to modify the properties for the specified guest. For each property, specify its name and desired value. Use “getprops” to see the current properties and values for the guest.

REST Request

PUT /sysadm/iohyve
{
  "ram" : "512M",
  "name" : "bsdguest",
  "action" : "setprop"
}

WebSocket Request

{
  "namespace" : "sysadm",
  "id" : "fooid",
  "args" : {
     "ram" : "512M",
     "name" : "bsdguest",
     "action" : "setprop"
  },
  "name" : "iohyve"
}

Response

{
 "args": {
   "setprop": {
     "bsdguest": {
       "ram": "512M"
     }
   }
 },
 "id": "fooid",
 "name": "response",
 "namespace": "sysadm"
}