Versions Compared

Old Version 123

changes.mady.by.user Koushik Das

Saved on

compared with

New Version Current

changes.mady.by.user user-fce10

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

...

  • 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
    • 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
    • uuidid: 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 e.g. "https://1-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

...

{ 
postURL:https://1-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,
uuidid:C7D351D2-F167-4CC8-A9FF-3BECB0A625C4
}

...

{ 
postURL:https://1-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,
uuidid:DD0A9FC6-C17E-4180-963C-870B9D03A80A
}

...

  • 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)
    • Custom HEADER field to be sent
      • X-metadata: encrypted data returned from getUploadParams API call: required
    • file: the location of the template/volume to be posted as multipart/form-data: required
      • X-signature: signature returned from getUploadParams API call: required
      • X-expires: expires returned from getUploadParams API call: required
    • request parameters
      • file: the location of the template/volume to be posted as multipart/form-data: required
  • Response:
    • '200 OK' on successful upload
    • '401 authorization error' incase 400 Bad Request' if any fields are empty or the signature key validation or any other validation failedfailed or the request expired or metadata cannot be decoded or the post request is already used
    • '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/errordue to some runtime exception
Volume upload request

curl -X POST "https://1-2-3-4.xyz.com/upload/C7D351D2-F167-4CC8-A9FF-3BECB0A625C4"  -F "file=@volume.vhd" -F "signature=H "X-signature:de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9" -F H "X-metadata=:TKPFeuz2nHmE/kcREEu24mnj1MrLdzOeJIHXR9HLIGgk56bkRJHaD0RRL2lds1rKKhrro4/PuleEh4YhRinhxaAmPpU4e55eprG8gTCX0ItyFAtlZViVdKXMew5Dfp4Qg8W9I1/IsDJd2Kas9/ftDQLiemAlPt0uS7Ou6asOCpifnBaKvhM4UGEjHSnni1KhBzjgEyDW3Y42HKJSSv58Sgmxl9LCewBX8vtn9tXKr+j4afj7Jlh7DFhyo9HOPC5ogR4hPBKqP7xF9tHxAyq6YqfBzsng3Xwe+Pb8TU1kFHg1l2DM4tY6ooW2h8lOhWUkrJu4hOAOeTeRtCjW3H452NKoeA1M8pKWuqMo5zRMti2u2hNZs0YY2yOy8oWMMG+lG0hvIlajqEU=" -F H "X-expires=:2014-10-17T12:00:00+0530" -vF "file=@volume.vhd" -v

Volume response

200 OK

upload successful.

Template upload request

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

Template response

200 OK

 upload successful.

Query status of uploaded template/volume

...

The SSVM agent will listen for any connections from Apache web server (using the NioServer utilitynetty server). It will be using the localhost and port number (come from a configuration8210) to listen.

SSVM apache proxies the data from https to http url on localhost:port using ProxyPass.

...

  • pre-validation errors (file upload hasn't started yet)
    • SSL handshake failed
    • params validation with PSK failed
    • max file size from the header crossed the limit
  • post validation error 
    • file successfully uploaded
      • file uploaded is not of the type specified (for ex: if the template is said to be of type tar, the actual downloaded file is not if this type)
      • max upload limit crossed
    • partial file upload (http errors can be caught through appropriate event handlers: exception,timeout,closed (http://hc.apache.org/httpcomponents-core-ga/tutorial/html/nio.html)))
      • user stopped/canceled the post request
      • user stopped/canceled the post request before completion
      • uploading the template failed due to a network issue
      • browser request timed out
      • browser crashed
      • SSVM is down/restarted
      • SSVM apache down/restarted
      • secondary storage is not accessible
      • there isn't enough space in secondary storage and hence agent can't write to it

...

  • Global configuration to limit the max upload size of template /volume - upload.post.max.size- max.template.iso.size (existing)

  • Global configuration to limit the max upload size of volume - storage.max.volume.upload.size (existing)

  • hidden configuration to save sha1 PSK on the management server - upload.post.psksecret.key
  • management server upload polling interval and polling timeout - upload.postmonitoring.interval, upload.postoperation.timeout
  • time interval at which the GC or cleanup thread should run - upload.post.gc.interval

...

  • The NFS Store url, path and some other information are exposed to the end user in the response to getUploadParams. This is done so that agent gets all the information required to upload the template with the POST request. One option can be to encrypt the The entire JSON and then send it will be encrypted using PSK and then sent across as part of getUploadParams response
  • The Apache web server will only accept upload requests over HTTPS
  • Proxy between apache and agent is internal to the SSVM. Hence no security threat here.
  • SSVM PSK location can only be accessed by admin. Hence no security threat.

...

  • To increase the number of parallel uploads, multiple SSVMs needs to be created. This will be handled automatically by the management server using the SSVM scale up mechanism (system.vm.auto.reserve.capacity, secstorage.capacity.standby and secstorage.session.max configuration variables). More uploads for a SSVM results in more polling related agent commands going to the SSVM and that should exhaust the session.max limit and result in spawning new SSVM. The SSVM selector logic then should pick up an SSVM during the request.
  • TBD: number of parallel uploads a single SSVM can handle
  • up an SSVM during the request.
  • TBD: number of parallel uploads a single SSVM can handle

Troubleshooting/logs

On the SSVM all the upload server related logs will be from a thread with name format nioEventLoopGroup-%d-%d.

On the Management Server, the upload monitor related logs will be from a thread with name format Upload-Monitor-%1

log4j xml can be tuned both on management server and SSVM to get logs at different levels.

UI Changes

UI to upload volume/template which should be able to accept "browse and upload" file. Existing UI for volume/template upload will be extended with the browser-based upload functionality.

...

  1. User navigates to the Templates page then switches to ISO using the "Select view" selector, then the user clicks on "Register ISO" (existing screen)
  2. Register ISO form pops up (existing screen)
  3. User has now the choice to provide URL of the volume/ISO (existing functionality) or Upload File from Browser (new functionality)
  4. Selects File Upload from Browser then specifies the volume/ISO file (Browse...) to be uploaded
  5. User fills in other existing form fields
  6. User clicks OK to submit the form
  7. Browser UI requests an unique upload URL using the getUploadParamsForVolume api call
  8. Management server returns an upload url, encrypted metadata string which should be passed on to the upload url while doing the upload
  9. Browser starts uploading using POST request to the upload URL
  10. The post request completes once the template is uploaded or there was an error uploading.
  11. The user can close the dialog (POST request should still be active) and use listvolumes API result to check the status of itrequest should still be active) and use listvolumes API result to check the status of it

Testing

Automation/marvin cases

https://git-wip-us.apache.org/repos/asf?p=cloudstack.git;a=commit;h=db7964fb11842ef008464e42e715838cbe46e72d

Manual Test Cases

Browser-based Template / Volume upload Test Plan

Open Issues

  1. PSK length - for now it can be a fixed length, later on it can be made configurable.

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

  3. Recommended configuration of SSVM and apache web server

...

Bug Reference & Branch

CLOUDSTACK-....7924

volumetemplate-upload branch off master

https://git-wip-us.apache.org/repos/asf?p=cloudstack.git;a=log;h=refs/heads/volume-upload