...

• Response
  • uuid: Unique UUID to identify the volume. This is used to query the status of volume after successful completion of upload
  • postURL: POST url to upload the file to; for e.g. "https://ssvmpublicip1-2-3-4.xyz.com/upload/uuid", where 1-2-3-4 is derived from SSVM public IP 1.2.3.4, and xyz.com is the domain name registered with Cloudstack. For more details refer to section "POST URL" below.
  • metadata: encrypted data to be sent in the POST request. This is used to transfer some internal meta-data required for upload
  • expires: the timestamp after which the signature expires
  • signature: signature is SHA1 key generated using PSK based on 'postURL', 'metadata' and 'expires' in the response. This is used to validate that the actual POST request to upload data is a genuine one

...

• Response
  • uuid: Unique UUID to identify the template. This is used to query the status of template after successful completion of upload
  • postURL: POST url to upload the file to; for  for e.g. "https://ssvmpublicip1-2-3-4.xyz.com/upload/uuid"., where 1-2-3-4 is derived from SSVM public IP 1.2.3.4, and xyz.com is the domain name registered with Cloudstack. For more details refer to section "POST URL" below.
  • metadata: encrypted data to be sent in the POST request. This is used to transfer some internal meta-data required for upload
  • expires: the timestamp after which the signature expires
  • signature: signature is SHA1 key generated using PSK based on 'postURL', 'metadata' and 'expires' in the response. This is used to validate that the actual POST request to upload data is a genuine one

GetUploadParamsForVolume API call

http://managementip:8080/client/api?command=getUploadParamsForVolume&response=json&sessionkey=TW1GLzPclNGgKtoYN5Xznbw8Nds%3D&name=windows&zoneId=c2bcad2f-1eb1-45ba-bebe-1c21873831b7&format=VHD&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Volume response

{ 
postURL:https://ssvmpublicip1-2-3-4.xyz.com/upload/C7D351D2-F167-4CC8-A9FF-3BECB0A625C4,
metadata:TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=,
signature:de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9,
expires: 2014-10-17T12:00:00+0530,
uuid:C7D351D2-F167-4CC8-A9FF-3BECB0A625C4
}

GetUploadParamsForTemplate API call

http://managementip:8080/client/api?command=getUploadParamsForTemplate&type=template&response=json&name=centos 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

Template response

{ 
postURL:https://ssvmpublicip1-2-3-4.xyz.com/upload/DD0A9FC6-C17E-4180-963C-870B9D03A80A,
metadata:TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=,
signature:de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9,
expires: 2014-10-17T12:00:00+0530,
uuid:DD0A9FC6-C17E-4180-963C-870B9D03A80A
}

POST URL to post the data on to SSVM. This post url is returned from the getUploadParamsForVolume/Template api calls

Ex: https://ssvmpublicip/upload/uuid: https://1-2-3-4.xyz.com/upload/uuid

As seen in the example, the URL has a domain name (in this case xyz.com) and a prefix (in this case 1-2-3-4). The reason for having a domain name is that SSL certs can only issued for a domain and not any IP address. The domain name to be used is configured using the global config "secstorage.ssl.cert.domain". The prefix is to identify the SSVM based on its public IP address. So if the public IP is 1.2.3.4 then the prefix is 1-2-3-4. This approach for generating the URL is already present in Cloudstack. Refer (1) and (2) for more details.

• As can be seen from the description of 'signature' above, the user should't tamper with the values of postURL, metadata, expires while making the POST request. Otherwise it would result in an upfront failure during POST request.
• Request: (this is a POST request)
  • metadata: 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://ssvmpublicip1-2-3-4.xyz.com/upload/C7D351D2-F167-4CC8-A9FF-3BECB0A625C4" -F "file=@volume.vhd" -F "signature=de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9" -F "metadata=TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=" -F "expires=2014-10-17T12:00:00+0530" -v

...

Template upload request

curl -X POST "https://ssvmpublicip1-2-3-4.xyz.com/upload/DD0A9FC6-C17E-4180-963C-870B9D03A80A" -F "file=@templatelocation.vhd" -F "signature=de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9" -F "metadata=TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=" -F "expires=2014-10-17T12:00:00+0530" -v

...

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

{ "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)","account":"admin","zoneid":"c2bcad2f-1eb1-45ba-bebe-1c21873831b7","zonename":"zone","status":"8% Downloaded","templatetype":"USER","hypervisor":"XenServer","domain":"ROOT","domainid":"fad51d88-449b-11e4-9cf2-2d5524b62490","isextractable":true,"details":{"hypervisortoolsversion":"xenserver61"},"tags":[],"sshkeyenabled":false,"isdynamicallyscalable":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.

...

1. SSL CA certificates - what kind of certificates will be used?
2. PSK length - for now it can be a fixed length, later on it can be made configurable.

3. Upload url should be active only for one call - Its partially handled now. The limitation needs to be addressed.

4. Recommended configuration of SSVM and apache web server
   

Reference

1. Procedure to Replace realhostip.com with Your Own Domain Name
2. Implementation details and troubleshooting - uploading custom domain certificate instead of using realhostip.com

Bug Reference & Branch

CLOUDSTACK-....

...