This feature allows administrators to use templates and ISOs without caching them on secondary storage. The usual process of virtual machine deployment is kept as before, with the only constraint that the task of downloading the template/ISO is delegated to the KVM agents instead of the SSVM agent.

Despite the feature is introduced into the version, and latest versions are recommended, as several fixes have been addressed and will be available from version onwards.


Pull Requests:

JIRA Ticket:  CLOUDSTACK-10146 - Getting issue details... STATUS

Feature Specification

This feature introduces a new way to use templates and ISOs in CloudStack, avoiding secondary storage as an intermediate cache.


  • Existing API methods 'registerTemplate' and 'registerIso' are both extended with a new optional boolean parameter 'directdownload'. When this new parameter is set to true, it will only allow KVM template/ISO registration, throwing an exception if hypervisor parameter is not 'KVM'. When 'directdownload' is set as true, templates and ISOs are both registered on CloudStack without any interaction with SSVM to initiate download to secondary storage. This way, template and ISO registration using direct download will only perform two tasks:
    • URL checking on a random KVM host, retrying 3 times in case of failure, and failing registration if URL cannot be reached.
    • Create entries on CloudStack database, specifically on template_store_ref. An entry is created for each direct download registered template on template_store_ref having:
      • Template/ISO ID on template_id column
      • Null store_id
      • Download_state = 'BYPASSED'
      • State = 'Ready'
        (These entries are only persisted on 'template_store_ref' for CloudStack to list direct download registered templates on the virtual machine deployment window)
    • Template/ISO checksum can also be provided as specified on FR25 as the 'checksum' parameter. Checksums are expected as {ALGORITHM}CHECKSUM, where:
      • ALGORITHM can be: 'MD5', 'SHA-256', 'SHA-512'
      • CHECKSUM is the hash value.
        This checksum is persisted on database on registration time and it will be used after template/ISO is downloaded on primary storage to compute checksum and compare with the one provided at registration time. If checksum validation fails after retrying 3 times, VM deployment fails.
  • A new API method 'uploadTemplateDirectDownloadCertificate' is added. It accepts a certificate, a certificate name and hypervisor type as required parameters, and uploads and import provided certificate to all running KVM hosts' cloud.jks keystore, in order to be used by templates or ISOs on HTTPS. This method´s response only indicates if the operation was successful.


Supported protocol for template/ISO registrations are: HTTP, HTTPS, NFS and METALINK.

For templates or ISOs on HTTP, the option to add request headers is provided, via vm_template_details. For each desired request header, a detail should be created, with:

  • key: 'HTTP_HEADER:HEADER' (example: HTTP_HEADER:Content-Type)
  • value: 'VALUE' (example: application/x-www-form-urlencoded)

Template/ISO registration allows metalinks for both direct download and SSVM download:

  • Metalink downloader fetches metalink XML file and examines it collecting URLs and checksums
  • Metalink URL may contain special characters as '?', '=', '&' to allow extra arguments.
  • Metalink downloader considers the optional tag "priority" for metalink URLs. In case priority tags are defined, URLs should be ordered ascending by the priority value.
  • If checksum is not provided on CloudStack when registering the template, one of the existing checksums on the metalink XML file is used for checksum validation.
  • Metalink downloader iterates through the existing URLs to download a template/ISO.

A retrying logic is defined for direct download, within the context of the start VM existing functionality, which would retry the following in case of failure:

  • Management server sends a download command to a host:
    • If the template cannot be downloaded on that host, another host is selected and download command sent. Random selection is performed, up to 2 times.
    • If the template was downloaded on the host but the checksum validation failed 3 times, then the deployment fails.
  • Agents receive download command:
    • If the template cannot be downloaded, answer to management server included: result=false and retryOnOtherHosts=true.
    • If the template was downloaded but the checksum validation fails:
      • Try 3 times: re downloading the template and perform checksum validation. If after 3 times it fails, sends an answer to management server including: result=false and retryOnOtherHosts=false


Specify that template is marked for direct download by clicking checkbox on registration window. Direct Download checkbox is displayed only when selected hypervisor is KVM. When Direct Download is selected, the checksum field is displayed.

The usual VM deployment/ISO attaching process remains unchanged.

  • No labels