Overview

The system consists of three major components -- a web front end, a RESTful web service and scripts.

• Front-end Layer: The web front end is where the user can create VM, query VM status, switch VM mode, and kill VM. 

• Web Service Layer: The RESTful web service takes user request and translates the requests to command lines to manage VM. The command lines are backed by the scripts. The web service also maintains VM status in a database. The web service can also be organized in a distributed manner, i.e., a request router dispatches user requests to web service in different machines.

• Hypervisor Layer: There are scripts used to create VM, configure network properly, switch VM mode, and kill VM. They are invoked by the web service with proper input parameters.

This document presents APIs for both web service layer and hypervisor layer. These APIs are for internal usage and there is no open access to them.

RESTful APIs and scripts APIs

Create VM

Below is an example how the service will call the script.

bash create_vm_script.sh --image /var/image_file --vcpu 2 --mem 1024 --wdir /var/instance/uuid/ --vnc port --ssh port --loginid vmloginid --loginpwd vmloginpwd

where

• /var/image_file is the original image which should be copied and pasted for each VM

• 2 is the number of cpu for the vm

• 1024 is the number of memory for the vm

• /var/instance/uuid/ is the working directory for vm with uuid

• ports for vnc and ssh are assigned permanently

• login username and password for this vm

Response

• succeeded (0) or failed (non-zero value). The script also prints out an error message. Use different return codes for different errors.

Update VM

Launch a VM

Below is an example how the service will call the script, where policy file is the configuration file for firewall.

bash launch_vm_script.sh --wdir /var/instance/uuid/ --mode {maintain|secure} --policy /path/to/policyfile

Response

• succeeded (0) or failed (non-zero value). The script also prints out an error message. Use different return codes for different errors.

Query a VM’s status

{	
	"status":[
			{
				"vncloginId":<vnc_userId>",
				"vcpus":<vcpu>,
				"vmInitialLoginPassword":<vm_pw>,
				"publicip":<ip>,
				"sshport":<port>,
				"vncport":<port>,
				"imageName":<imagename>,
				"vncloginPassword":<vnc_pw>,
				"memSize":<mem>,
				"volumeSize":<volumesize>,
				"vmInitialLoginId":<login_id>,
				"pubKeyExists":<public_key_exists>,
				"mode":<mode>,
				"vmid":<vmid>,
				"state":<state>,
            	"desc_links": <desc_links>,
            	"desc_nature": <desc_nature>,
            	"desc_outside_data": <desc_outside_data>,
            	"desc_requirement": <desc_requirement>,
            	"desc_shared": <desc_shared>,
            	"rr_data_files": <rr_data_files>,
            	"rr_result_usage": <rr_result_usage>,  
            	"title": <title>,
            	"tou": true/false,
            	"type": <type>,      
            	"pubKeyExists": true/false,
 				"consent": true/false, 
            	"full_access": null/true/false,
                "roles": [
                	{
                    	"email": <user_email>,
                    	"full_access": <user's_full_access>,
                    	"guid": <user_guid>,
                    	"role": <"OWNER-CONTROLLER"/"OWNER"/"CONTROLLER"/"SHAREE">
                    	"tou": true
                	}
            	]
		}
	]
}

bash query_vm_status_script.sh --wdir /var/instance/uuid/

Response

• succeeded (0) or failed (non-zero value).

• If succeeded, prints status response with key/value separated by colon, and each value pair separated by a newline. For example, 

mode: security status: running publicip: 192.168.1.1 

• The script also prints out an error message. Use different return codes for different errors.

Switch a VM’s mode

Below is an example how the service will call the script.

bash switch_vm_script.sh --wdir /var/instance/uuid/ --mode secure --policy /path/to/policy/file

response

• succeeded or failed

Stop a VM

Below is an example how the service will call the script.

bash stop_vm_script.sh --wdir /var/instance/uuid/

response

• succeeded or failed

Delete a VM

bash delete_vm_script.sh --wdir /var/instance/uuid/

• succeeded or failed

List VMs

{	
	"vmsInfo":[
			{
				"created_at":<created_at>,
				"host":<ip>,
				"memorySize":<memorySize>,
				"numCPUs":<numCPUs>,
				"numHostCPUCores":<numHostCPUCores>,
				"numHostMemoryGB":<numHostMemoryGB>,
				"vmmode":<mode>,
				"vmid":<vmid>,
				"vmState":<state>, 
            	"type": <type>,      
                "roles": [
                	{
                    	"email": <user_email>,
                    	"full_access": <user's_full_access>,
                    	"guid": <user_guid>,
                    	"role": <"OWNER-CONTROLLER"/"OWNER"/"CONTROLLER"/"SHAREE">
                    	"tou": true
                	}
            	],
				"userEmail":null,
				"username":null
		}
	]
}

List available VM images

Update User Key

Update User Email

Update User Key

Migrate Vm

Add VM Sharee

Remove VM Sharee

Manage Controller