Child pages
  • For Developers: Developer API
Skip to end of metadata
Go to start of metadata
This is a set of APIs exposed by the web services and back-end scripts. This is for advanced users that want to implement their own version of the data capsule, and will likely not concern HTRC Data Capsule users.

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. The web front end is hosted in http://htrc5.pti.indiana.edu:9443/login 

  • 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

 

RESTful call

/createvm

Purpose

create a vm

Method

POST

Input Parameter

imagename=<imagename>&loginusername=<loginusername>& loginpassword=<loginpassword>&vcpu=<vcpu>&memory=<memory>

Response

200 - {vmid:<uuid>},

400 - no vm is found,

500 - internal error

 

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.

Launch a VM

 

RESTful call

/launchvm

Purpose

launch a vm

Method

POST

Input Parameter

vmid=<vmid>

Response

200 - operation is in progress,

400 - no vm is found,

500 - internal error

 

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

 

RESTful call

/show

Purpose

show vm status

Method

POST

Input Parameter

vmid=<uuid> (if no vmid is present, info of all vm relative to this username will be returned)

Response

200: {{

vmid:<vmid>, mode:<mode>, state:<state>, vnc-port:<port>, ssh-port:<port> (invisible in secure mode), publicip:<ip>, vcpu:<vcpu>, mem:<mem>, volumesize:<volumesize>, imagename:<imagename>

}

}

400 - no vm is found,

500 - internal error


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

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

 

RESTful call

/switchvm

Purpose

switch vm mode: modes are “maintenance” and “secure”.  

Method

POST

Input Parameter

vmid=<uuid>&mode=<mode>

Response

200 - operation is in progress,

400 - no vm is found,

500 - internal error

 

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

 

RESTful call

/stopvm

Purpose

stop vm : moves VM from running state to stopped state.  This is the same effect as turning a "machine" off by pushing it's power button.  A stopped VM can be restarted via /launchvm.

Method

POST

Input Parameter

vmid=<uuid>

Response

200 - operation is in progress,

400 - no vm is found,

500 - internal error

 

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

 

RESTful call

/deletevm

Purpose

delete vm. All files under vm working directory (VM image, secure volume, etc) are permanently deleted.

Method

POST

Input Parameter

vmid=<uuid>

More secure option: Add in a user's authentication token that is verified by the script.

Response

200 - operation is in progress,

400 - no vm is found,

500 - internal error


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

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

response

  • succeeded or failed

List available VM images

 

RESTful call

/listimage

Purpose

list available image names

Method

GET

Response

200 - {{imagename:<image_name>}}

500 - internal error

 

 

 

 

  • No labels