Existing CloudStack supports legacy boot loader BIOS by default for Guest VM’s booting on Hypervisor(Xen, VMware, KVM etc). In Virtualization, hypervisor emulates the hardware for the Guest VM.  BIOS {Basic Input-Output system} is a low-level software. The BIOS loads when a VM starts up, and the BIOS is responsible for waking up your VM’s hardware(emulated) components, ensures they are functioning properly, and then runs the boot loader that boots Windows or whatever other operating system have installed.

The traditional BIOS still has serious limitations. It can only boot from drives of two 1 TB or less. 3 TB drives are now common, and a computer with a BIOS can’t boot from them. That limitation is due to the way the BIOS’s Master Boot Record system works. BIOS can be used in devices that do not require large storage or security. UEFI { Unified Extensible Firmware Interface} can work alongside BIOS. It can sit on top of BIOS and work independently. 

UEFI supports two modes 

  1. Legacy Boot :-  legacy boot mode is similar to BIOS boot mode.  UEFI serves as software driven and bare bones to operating systems, and is responsible for initialising the hardware of a device
  2. Secure Boot :-  secure boot mode is designed to protects operating system against malicious code being loaded and executed early in the boot process, before the operating system has been loaded. On each boot-up, the UEFI firmware inspects each EFI binary that is loaded and ensures that it has either a valid signature (backed by a locally trusted certificate) or that the binary's checksum is present on an allowed list. Secure boot mode is still evolving and yet to be matured.


The feature is to enable UEFI boot mode for Guest VM launched from CloudStack.


  1. Cloud admin will have to perform the below configuration 
    • Host Configuration if any required { eg: KVM host additional OVMF package is required to  boot Guest VM in UEFI mode}
    • Guest VM template configurations such as like rebuild the existing template and enable with UEFI boot loader 
  2. Cloud admin is supposed to perform below operations prior to Guest VM launching.
    • registering UEFI enabled template (follow same process as normal template)
    • in case of UEFI Guest VM, selecting the appropriate template 
  3. Template details page will be remains same, there will be no additional meta data regarding UEFI in UI page for template details.





Document History




Pavan Kumar Aravapalli

First revision

24 Oct 2019


  • NA

Use case

  1. User wants to deploy an instance with boot mode as UEFI (legacy)
  2. User wants to deploy an instance with boot mode as UEFI (secure boot)

Feature specification

  1. Support UEFI boot mode options in VM deploy wizard.
  2. While on-boarding a Host to CloudStack, Detect whether a host is UEFI ready OR not, and update host table in DB. This information should be visible in UI as well as listHosts response.
  3. During instance deployment
    • Ensure planner considers only those hosts that are UEFI enabled (as per DB) for allocation.
    • Configure VM on hypervisor accordingly if any required. For example in case of kvm extra xml definitions to be inserted for GuestVM def.
  4. No change in the existing functionality/ vm operations  (only boot loader mode should be affected on the basis of flag for the  target hypervisor, every thing else is  same as the previous behaviour)

Test guidelines

  1. Deploy Guest VM with UEFI boot type and Legacy/Secure boot mode.
  2.  Guest VM should take lesser boot time compared to legacy boot loader.
  3.  Guest VM should display respective UEFI boot loader display while booting on the console.
  4.  User should be able to perform all VM’s operation as they were able to do earlier.

Error handling

  1.  User will be provided with alert in case of VM creation process fails.
  2.  All errors at various levels of operations will be logged in management-server.log.

Audit Events

 Events will be generated in the management server logs for the VM being created during the course of the boot loading process.

Target users

CloudStack Users and Admins.

Current behaviour

Existing CloudStack supports legacy boot loader BIOS by default for Guest VM’s running on Hypervisor like XEN, VMware, KVM etc. The behaviour with respect to each hypervisor below.


By default BIOS legacy boot loader is selected, When an instance is deployed on VMware ESXI host using CloudStack UI. 


By default BIOS legacy boot loader is selected, When an instance is deployed on Xen host using CloudStack UI. 


By default BIOS legacy boot loader is selected, When an instance is deployed on KVM host using CloudStack UI.  KVM by default does not come with UEFI boot out of the box. 

Design description

  1. Deploy VM 'review' Wizard  added with new select drop downs "Boot Type[UEFI,BIOS]", "Boot Mode[LEGACY, SECURE]".  Once the Deploy VM request is submitted with params [Boot type, Boot Mode] , same information will be persisted in CloudStack 'cloud' DB in table 'user_vm_details' as [<id>,<vm-id>,<UEFI or BIOS>,<LEGACY or SECURE>,<1>]. In case of deployed Guest VM Boot information is BIOS  and LEGACY by default and there won't any functionality changes. Once VM is deployed in either UEFI or BIOS mode remains in the same mode till it's end of life cycle and can't be altered.
  2. Once resource availability and authentication done, user vm deploy job is submitted to VM Job queue. Job Framework will handle the rest of the work flow for vm deploy. In order to deploy the Guest VM in UEFI enabled Host  Deployment Planner and Allocator are extended with UEFI support. 
  3. ServerDiscovery functionality is extended with UEFI feature detection while adding/on-boarding a Host [KVM,VMware] in CloudStack. When a new Host is on-boarded to CloudStack , additional detail information is inserted in 'host_details' table as [<id>,<host_id>,Host.Uefi.Enable,<Yes or No>].
  4. VM deploy process happens using deployment planner. Since all the Hosts listed by the Planner in the deployment plan may not support UEFI boot , additional care need to be taken in case of UEFI enabled VM Deploy. While the selected planner picking the available hosts , additional constraint will be added to get host list.  
  5. Deployment Planner Changes : 
    • Guest VM deployed with out UEFI Boot Loader
       In this scenario planner behaviour is same as earlier , it will try at the CPU and memory capacity of the cluster to create an ordered cluster list. And based on the least utilised Cluster it will returns the Cluster List for the deployment Allocator.
    • Guest VM deployed with UEFI Boot Loader
      Where as in this scenario it returns the Cluster List based on the resource availability And the cluster  list is reordered to protect the Host with UEFI capabilities. 
    • Guest VM deployed with UEFI Boot Loader
      DeployVM Cmd additional params will be considered in this use case, and try to fetch Hosts with UEFI capability List. Cluster List which is given by FirstFit Planner will get retained with the constraint that hosts which are not supporting UEFI capability. In case of no Host Available in the current cluster then as per the existing CloudStack framework it try's to deploy in other cluster and looks for the host with UEFI capability.
    • Guest VM deployed with out UEFI Boot Loader
      Nothing changed in the behaviour, it will be like as previous.
    • FirstFitPlanner is handled two cases 
    • FirstFit Allocator Changes:
  6. Add Host Command get the information from the ServerDiscovery Resource layer, whether  Host supports UEFI boot or not. If host supports uefi, host information will be updated in host_details table as explained in (point 3). 
  7. It's not supported In case of existing [KVM]Host to be updated with UEFI capabilities once it's added.
  8. In order to support legacy behaviour by default  ['Uefi Supported','No'] considered for the existing Host.
  9. UEFI support is prohibited for migrating the VM to another host in cluster , in this implementation. It can be addressed in future release as Enhancement.
  10. Host Changes


    1. KVM Host ( RHEL / CENT OS 7.x above version) along with agent , additional edk2-ovmf/OVMF  package should be installed
    2. Libvirt configuration changes like adding nvram config param in /etc/libvirt/qemu.conf
    3. UEFI related params information added in which is located /etc/cloudstack/agent
    4. In case of newly configuring KVM Host , Cloud Admin [Customer admin] will have to prepare and add after successful completion of agent.


    • Check whether specified VM supports secure UEFI boot mode OR not.
    • Update VM configuration to use UEFI legacy mode for booting
    • Ensure when host is added, to check if it supports (UEFI legacy OR UEFI secure) boot modes, and update DB accordingly. This information should be displayed in UI as well as listHost response.
    • Both IDE and SATA controllers can be used in UEFI booted VM for CDROM drives. But preferred controller is SATA where ever EFI firmware is recommended. Hence instance will be configured with SATA CDROM at virtual node "0:0". In case of DHCP offload scenario, the user instance will have config-drive ISO image mounted on IDE controller at "0:1" which is same as the instance booted with BIOS that contains all CDROM drives on IDE controller only. Hence irrespective of BIOS or EFI boot mode every instance deployed by CloudStack will have IDE 0:1 node reserved only for config drive ISO image purpose.

11. Design should support the legacy feature with out any deviation in the functionality. 

Protecting non-UEFI instances from being deployed on UEFI capable hosts

Default first fit planner only look at the CPU and memory capacity of the cluster to create an ordered cluster list. The (host) allocator then goes over the hosts in a cluster to find a suitable host for deployment. Since the default planner isn't aware of the UEFI capabilities of a host, it may lead to a situation where VMs not requiring UEFI capabilities use up CPU/memory resources on UEFI capable host. To address this issue the cluster list needs to ordered such that for non-UEFI VMs, clusters with UEFI hosts are towards the end of the ordered list. 

 Known Things 

  1. Xenserver 8.x UEFI [Only Legacy mode]features is supported and it's a alpha release which is for trial purpose.
  2. Once a VM is deployed in normal boot from CloudStack, then UEFI boot support is prohibited for the same Guest VM and can't perform UEFI boot from the CloudStack again.
  3. Once a VM is deployed in UEFI boot from CloudStack , then normal boot support is prohibited for the same Guest VM and can't perform normal boot from the CloudStack again. 


  1. assumption is that UEFI boot loader change affected only for User VM’s , System VM’s remains with the legacy loader. 
  2. KVM Hypervisor Limitation : 
    • OVFM supports only epel 7 release. 
    • Secure boot in KVM requires SMM,EPT host hardware capabilities
    • Secure boot in KVM requires , guest vm chipset of type q35
    • Once Host is on-boarded to CloudStack with Uefi Capability [Yer or No], UEFI details can't be modified. 
    • Incase of existing host to get updated UEFI Support 'Yes' Feature is not supported.
  3. Secure Boot in RHEL 7 Host is not supported from CloudStack as it requires RHEV Subscription
  4. Guest VM which is deployed in UEFI mode , restricted to migrate another Host[with UEFI capability].
  5. Conversion of an instance's boot type is not allowed from any type to any type
    • If VM was deployed with BIOS as firmware, then it is not allowed to modify the firmware to UEFI  or vice a versa.
    • If VM was deployed with UEFI as firmware and boot mode as legacy boot, then later its not allowed to modify the boot mode to secure boot or vice a versa.

Work Flow

  1. Go to Deploy VM wizard , submit request with UEFI boot enabled 

API Changes

Introduced new params [ bootMode, bootType] for the deployVirtualMachine API's. 

bootType, bootMode are not  a mandatory params. 

bootType: Guest VM Boot option either custom[UEFI] or default [BIOS]

bootMode: Boot Mode [ Legacy ] or [ Secure ] applicable when boot type selected is UEFI, otherwise [Legacy] by default for BIOS

DB Changes


Hypervisors supported

KVM, VMware, Xen(alpha version)

UI Changes

  1. Enable deploy VM wizard Offer wizard with UEFI param[Boot type, Boot Mode]
  2. If the host is UEFI enabled, details page will be updated like shown below 
  3. Display VM Instance detail with UEFI information either enabled or disabled




Open Items/Questions

  1. UEFI enabled template provision/ support to be taken care by Customer Cloud Admin. 



  • No labels