Versions Compared

Old Version 115

changes.mady.by.user Gabor Apati-Nagy

Saved on

compared with

New Version 116

changes.mady.by.user Koushik Das

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Management Server generates a unique pre-shared key (PSK) and shares it with the SSVM agent. 
  2. New API request "getUploadParams" encoded the usual Cloudstack API way using api keys. Request parameters include format, hypervisor, md5 sum etc.
  3. Management Server response to (b) returns post url to upload the file, encrypted payload to send to the url while uploading the file and a SHA1 signature generated using PSK and params json.  
  4. User should upload the file over https POST request to the url obtained in (c). The signature and payload returned in (c) should be passed as is.
  5. The Apache web server on the SSVM matches the url, decrypts and passes on to the SSVM java agent as plain HTTP. The SSVM agent checks the signature against the decrypted payload using the key PSK and SHA1. Once the payload is verified, it writes to the NFS storage to the location encoded in the URL. 
  6. Once the upload completes, the MD5 checksum is compared (if available from step c).

API changes

A new API getUploadParams New APIs getUploadParamsForVolume/getUploadParamsForTemplate to enable users to upload volume/template from a local or network file share. The API response has a POST URL to which the volume/template needs to be uploaded. This is These are available to regular and admin users of Cloudstack. The request and response parameters are described below. Required parameters are marked with 'required'. Some of the parameters are exclusive for admin user and are marked 'admin only'.

GetUploadParamsForVolume
  • RequestRequest
      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. Defaulted to account name of caller if not specified.
    • domainid: an optional domain to which the account belongs. If the account parameter is used, 'domainid' must also be used. Defaulted to domain of the caller if not specified.
    • projectid: the UUID of the project if the volume /template needs to be associated with one'type' specified as volume
    • imagestoreuuid: the UUID of the 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)
    • diskofferingid: the UUID of the disk offering. This must be a custom disk offering as the volume size is not known before the actual upload. If not specified the default custom disk offering is used.
  • 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://ssvmpublicip/upload/uuid".
    • 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. This is used to validate that the actual POST request to upload data is a genuine one
GetUploadParamsForTemplate
  • Request
    • name: the name of the template : required
    • format: the format of the template to be uploaded. Possible values for template include QCOW2, RAW and VHD : required
    • zoneid: the UUID of the zone the template is associated to : required
    • displaytext: the display text of the template. This is used for setting a suitable name for display purposes. : required
    • hypervisor: the target hypervisor for the template : required
    • ostypeid: the UUID of the OS type that best represents the OS of this template : required
    • checksum: the MD5 checksum of template to be uploaded. If specified this is used to validate the content of the uploaded template for integrity.
    • account: an optional account name. Must be used with 'domainid' parameter below. Defaulted to account name of caller if not specified.
    • domainid: an optional domain to which the account belongs. If the account parameter is used, 'domainid' must also be used. Defaulted to domain of the caller if not specified.
    • projectid: the UUID of the project if the template needs to be associated with one'type' specified as template
    • displaytext: the display text of the template. This is used for setting a suitable name for display purposes. : required
    • hypervisor: the target hypervisor for the template : 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: additional 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. Default is false. : admin only
    • ispublic: true if the template is available to all users. Default is true. Regular users are allowed to create public templates based on global config 'allow.public.user.templates'
    • isrouting: true if the template type is routing i.e. if template is used to deploy router : admin only
    • passwordenabled: true if the template supports the password reset feature. Default is false.
    • requireshvm: true if this template requires hardware assisted virtualization support
    • sshkeyenabled: true if the template supports the sshkey upload feature. Default is false.
    • templatetag: the tag for this template. Used to deploy VMs on hosts with this tag. : admin only
  • 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: 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. This is used to validate that the actual POST request to upload data is a genuine one one

...

GetUploadParamsForVolume API call

...

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

...

{ 
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
}

...

GetUploadParamsForTemplate API call

...

http://managementip:8080/client/api?command=getUploadParamsgetUploadParamsForTemplate&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

...

{ 
postURL:https://ssvmpublicip/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
}

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

...