DUE TO SPAM, SIGN-UP IS DISABLED. Goto Selfserve wiki signup and request an account.
Page History
...
- Request
- type: type of upload request. Possible values are volume or template : required
- name: the name of the volume/template : required
- format: the format of the volume/template to be uploaded. Possible values for volume include QCOW2, OVA and VHD. Possible values for template include QCOW2, RAW and VHD : required
- zoneid: the UUID of the zone the volume/template is associated to : required
- checksum: the MD5 checksum of volume/template to be uploaded. If specified this is used to validate the content of the uploaded volume/template for integrity.
- account: an optional account name. Must be used with 'domainid' parameter below.
- domainid: an optional domain to which the account belongs. If the account parameter is used, 'domainid' must also be used.
- projectid: the UUID of the project if the volume/template needs to be associated with one
- 'type' specified as volume
- formatimagestoreuuid: the format UUID of the volume to be uploaded. Possible values include QCOW2, OVA and VHD : required
- name: the name of the volume : required
- checksum: the MD5 checksum of volume to be uploaded. If specified this is used to validate the content of the uploaded volume for integrity.
- imagestoreuuid: the UUID of the storage pool where the uploaded volume gets stored. This can be obtained storage pool where the uploaded volume gets stored. This can be obtained using listImageStores API call (https://cloudstack.apache.org/docs/api/apidocs-4.4/root_admin/listImageStores.html)
- 'type' specified as template
- displaytext: the display text of the template. This is used for display setting a suitable name for display purposes. : required
- format: the format of the template to be uploaded. Possible values include QCOW2, RAW and VHD : required
- hypervisor: the target hypervisor for the template : requiredname: the name of the template. Mostly set based on some internal naming convention : required
- ostypeid: the UUID of the OS type that best represents the OS of this template : required
- bits: specifies if template supports 32 or 64 bit. Default is 64 bit.
- details: template details in key/value pairs
- isdynamicallyscalable: true if template contains XS/VMWare tools in order to support dynamic scaling of VM cpu/memory
- isextractable: true if the template or its derivatives are extractable. Default is false
- isfeatured: true if the template is a featured template, false otherwise
- ispublic: true if the template is available to all users. Default is true.
- isrouting: true if the template type is routing i.e., if template is used to deploy router
- passwordenabled: true if the template supports the password reset feature. Default is false.
- requireshvm: true if this template requires HVM hardware assisted virtualization support
- sshkeyenabled: true if the template supports the sshkey upload feature. Default is false.
- templatetag: the tag for this template.
- Response
- uuid: Unique UUID to identify the template/volume. This is used to query the status of volume/template after successful completion of upload
- postURL: POST url to upload the file to; for e.g. "https://ssvmpublicip/upload/uuid".
- payload: payload encrypted data to be sent in the POST request. This is used to transfer some internal data required for upload
- expires: the timestamp after which the signature expires
- signature: signature is SHA1 key generated using PSK based on 'postURL', 'payload' and 'expires' in the response.
POST URL to post the data on to SSVM. This post url is returned from the getUploadParams api call Ex: https://ssvmpublicip/upload/uuid
- Request: (this is a POST request)
- payload: JSON string of parameters returned from getUploadParams API call: required
- file: the location of the template/volume to be posted as multipart/form-data: required
- signature: signature returned from getUploadParams API call: required
- expires: expires returned from getUploadParams API call: required
- Response:
- '200 OK' on successful upload
- '401 authorization error' incase the signature key validation or any other validation failed
- '500 internal server error' incase the file upload fails with clear error message
- '409 conflict' incase there is already another upload with same params in-progress/success/error
Query status of uploaded template/volume
User should be able to query the status of uploaded template/volume by calling listtemplates/listvolumes API with unique uuid obtained as part of the getUploadParams response (present in POST URL as mentioned above). The polling for status should start on successful completion of the POST request.
Failed uploads
If the template/volume fails to upload (HTTP code other than 200 OK), the user should request for a new upload url and upload it again. The same upload URL shouldn't be reused.
Example
Management server API
Request
template
- This is used to validate that the actual POST request to upload data is a genuine one
getUploadParams for volume
Volume response
{
postURL:https://ssvmpublicip/upload/C7D351D2-F167-4CC8-A9FF-3BECB0A625C4,
payload:TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=,
signature:de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9,
expires: 2014-10-17T12:00:00+0530,
uuid:C7D351D2-F167-4CC8-A9FF-3BECB0A625C4
}
getUploadParams for template
http://managementip:8080/client/ http://managementip:8080/client/api?command=getUploadParams&type=template&response=json&name=centos 64 64 64bit&displayText=centos 64 64bit&zoneid=-1&format=VHD&isextractable=false&passwordEnabled=false&isdynamicallyscalable=false&osTypeId=1b510c30-3352-11e4-aaca-a5c7f57670d0&hypervisor=XenServer&requireshvm=false&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
volume
http://managementip:8080/client/api?command=getUploadParams&response=json&sessionkey=TW1GLzPclNGgKtoYN5Xznbw8Nds%3D&name=windows&zoneId=c2bcad2f-1eb1-45ba-bebe-1c21873831b7&format=VHD-a5c7f57670d0&hypervisor=XenServer&requireshvm=false&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
...
Template response
template
{
postURL:https://ssvmpublicip/upload//upload/DD0A9FC6-C17E-4180-963C-870B9D03A80A,
payload:TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=,
signature:de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9,
expires: 2014-10-17T12:00:00+0530,
uuid:DD0A9FC6-C17E-4180-963C-870B9D03A80A,
payload:TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=,
signature:de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9,
expires: 2014-10-17T12:00:00+0530,
uuid:DD0A9FC6-C17E-4180-963C-870B9D03A80A
}
volume
{
postURL:https://ssvmpublicip/upload/C7D351D2-F167-4CC8-A9FF-3BECB0A625C4,
payload:TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=,
signature:de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9,
expires: 2014-10-17T12:00:00+0530,
uuid:C7D351D2-F167-4CC8-A9FF-3BECB0A625C4
}
File upload
Request
template
}
POST URL to post the data on to SSVM. This post url is returned from the getUploadParams api call Ex: https://ssvmpublicip/upload/uuid
- As can be seen from the description of 'signature' above, the user should't tamper with the values of postURL, payload, expires while making the POST request. Otherwise it would result in an upfront failure during POST request.
- Request: (this is a POST request)
- payload: encrypted data returned from getUploadParams API call: required
- file: the location of the template/volume to be posted as multipart/form-data: required
- signature: signature returned from getUploadParams API call: required
- expires: expires returned from getUploadParams API call: required
- Response:
- '200 OK' on successful upload
- '401 authorization error' incase the signature key validation or any other validation failed
- '500 internal server error' incase the file upload fails with clear error message
- '409 conflict' incase there is already another upload with same params in-progress/success/error
Volume upload request
curl -X POST "https://ssvmpublicip/upload/DD0A9FC6C7D351D2-C17EF167-41804CC8-963CA9FF-870B9D03A80A3BECB0A625C4" -F "file=@templatelocation@volume.vhd" -F "signature=de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9" -F "payload=TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=" -F "expires=2014-10-17T12:00:00+0530" -v
volume
Volume response
200 OK
Template upload request
curl -X POST "https://ssvmpublicip/upload/C7D351D2DD0A9FC6-F167C17E-4CC84180-A9FF963C-3BECB0A625C4870B9D03A80A" -F "file=@volume@templatelocation.vhd" -F "signature=de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9" -F "payload=TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=" -F "expires=2014-10-17T12:00:00+0530" -v
...
Template response
template
200 OK
volume
200 OK
template status
request
template
http://managementip:8080/client/api?command=listTemplates&response=json&templatefilter=self&id=DD0A9FC6-C17E-4180-963C-870B9D03A80A&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
volume
Query status of uploaded template/volume
User should be able to query the status of uploaded template/volume by calling listtemplates/listvolumes API with unique uuid obtained as part of the getUploadParams response (present in POST URL as mentioned above). The polling for status should start on successful completion of the POST request.
Volume status check request
http://managementip:8080/client/api?command=listVolumes&id=C7D351D2-F167-4CC8-A9FF-3BECB0A625C4&response=json&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
Volume status response
template
...
{ "
...
listvolumesresponse" : { "count":1 ,"
...
volume" : [ {
...
"id":"C7D351D2-F167-4CC8-A9FF-3BECB0A625C4","name":"windows","zoneid":"
...
c2bcad2f-
...
1eb1-
...
45ba-
...
bebe-1c21873831b7","zonename":"zone","
...
type":"
...
DATADISK","
...
provisioningtype":"
...
thin","
...
size":
...
0,"created":"2014-10-
...
17T15:
...
24:
...
06+0530","
...
state":
...
"
...
Uploading"
...
,"
...
account":"
...
admin","
...
domainid":
...
"fad51d88-449b-11e4-9cf2-2d5524b62490","domain":"ROOT","storagetype":"shared","hypervisor":"XenServer","diskofferingid":"a1bb6667-780c-47ad-91cb-b98aed589c18","diskofferingname":"Custom","diskofferingdisplaytext":"Custom Disk","destroyed":false,"isextractable":true,"status":"1% Uploaded","tags":[],"displayvolume":true,"quiescevm":false} ] } }
Template status check request
http://managementip:8080/client/api?command=listTemplates&response=json&templatefilter=self&id=DD0A9FC6-C17E-4180-963C-870B9D03A80A&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
Template status response
{ "listtemplatesresponse" : { "count":1 ,"template" : [ {"id":"DD0A9FC6-C17E-4180-963C-870B9D03A80A","name":"centos 64 64bit","displaytext":"centos 64 64bit","ispublic":false,"created":"2014-10-17T10:54:40+0530","isready":false,"passwordenabled":false,"format":"tar","isfeatured":false,"crossZones":false,"ostypeid":"1b510c30-3352-11e4-aaca-a5c7f57670d0","ostypename":"CentOS 6.2 (64-bit)
volume
{ "listvolumesresponse" : { "count":1 ,"volume" : [ {"id":"C7D351D2-F167-4CC8-A9FF-3BECB0A625C4","name":"windows","zoneid":"c2bcad2f-1eb1-45ba-bebe-1c21873831b7","zonename":"zone","type":"DATADISK","provisioningtype":"thin","size":0,"created":"2014-10-17T15:24:06+0530","state":"Uploading","account":"admin","domainidzoneid":"fad51d88c2bcad2f-449b1eb1-11e445ba-9cf2bebe-2d5524b624901c21873831b7","domainzonename":"ROOTzone","storagetypestatus":"shared8% Downloaded","hypervisortemplatetype":"XenServerUSER","diskofferingidhypervisor":"a1bb6667-780c-47ad-91cb-b98aed589c18XenServer","diskofferingnamedomain":"CustomROOT","diskofferingdisplaytextdomainid":"Custom Diskfad51d88-449b-11e4-9cf2-2d5524b62490","destroyedisextractable":falsetrue,"isextractabledetails":true,{"statushypervisortoolsversion":"1% Uploadedxenserver61"},"tags":[],"displayvolumesshkeyenabled":truefalse,"quiescevmisdynamicallyscalable":false} ] } }
Failed uploads
If the template/volume fails to upload (HTTP code other than 200 OK), the user should request for a new upload url and upload it again. The same upload URL shouldn't be reused.
Design
Pre-shared key management
...
Overview
Content Tools