Bug Reference



Apache CloudStack master branch


To access virtual disks, CD/DVD-ROM, and SCSI devices, a virtual machine uses storage controllers.

Virtual storage controllers appear to a virtual machine as different types of controllers of type IDE or SCSI. Further SCSI controllers can be classified into 4 sub types, as below

  • BusLogic Parallel
  • LSI Logic Parallel,
  • LSI Logic SAS
  • VMware Paravirtual SCSI

 Currently CloudStack supports following combinations only.

  • DATA volumes - SCSI controller (LSI Logic Parallel) - Hard coded in source code, no option for user to edit/choose the controller type
  • ROOT volumes - IDE or SCSI (LSI Logic Parallel) - Baed on value of global configuration parameter "vmware.root.disk.controller"

Currently the instances are deployed with the the LSI Parallel controller type. This might result in failure to boot when attempting to deploy templates that use the LSI SAS controller.


This is functional specification document of feature "Granular SCSI Controller support in CloudStack over VMware deployments" which has Jira ID CLOUDSTACK-4787.


Use Cases

  1. User template already has drivers that can support specific disk controller (listed below). User instances created from this template need to use that specific disk controller to be used to attach volumes to the user instance.
  2. Storage infrastructure has high end SAN infrastructure and admin user would like to leverage the high end environment for better I/O performance for user instances. Scsi disk controller sub types lsilogic SAS and PVSCSI are best suited for such environments. Hence user should be able to choose a specific disk controller to be used at cloud level (global configuration setting) or at template level (through an optional parameter that can be supported by API that registers the template)
  3. Certain operating system images might not have disk drivers in the OS image from factory by default. In such cases, admin user might want to avoid a specific disk controller, which is not supported by OS by default, to be used during deployment of user instance.
  4. Each operating system might have a recommended disk controller specified by the vendor of OS and/or hypervisor that suits best for the pair (OS instance running on specific hypervisor) to the best possible performance. Admin user might like CloudStack to detect the recommended disk controller while deploying user instance and later on use it while attaching volumes to the user instance.


Legacy user instance - A user instance deployed before CloudStack is upgraded to the versoin of CloudStack when this feature is introduced first.

Feature Specification

  1. CloudStack should provide administrator the means to choose the type of disk controller (including sub types listed in introduction section above) for an instance. The controller to be used by VM to access virtual disk (volume) can decided for various reasons. Some of them are listed here,
    1. Some controllers are optimized for best performance over specific backend infrastructure like SAN. Ex: VMware Paravirtual SCSI
    2. Compatibility of some controllers with VM's virtual hardware version or guest operating system.
    3. Operating system vendor recommendation and default set of drivers distributed as part of operating system image. Ex: Windows 8.1 ISO doesn't have Lsi Logic Parallel SCSI drivers by default. Hence a virtual disk attached to this controller won't accessible during installation of OS using the ISO.
  2. CloudStack should provide administrator an option which auto detects the recommended disk controller for the instance's guest operating system and applicable virtual hardware version.
  3. The choice of controllers mentioned in (1) & (2) is applicable only for user instances.
  4. Support backward compatibility - CloudStack should ensure legacy user instances are un-changed. Means existing user instance should not be affected by the administrator's choice mentioned in (1) & (2)
    1. Stopping & starting of legacy user instance should not affect the controller type in use for root & data volumes.
    2. Resetting a legacy user instance (RestoreVMCommand) of legacy instance should not affect the controller type in use for root & data volumes.
    3. Rebooting a legacy user instance
  5. A modification of global configuration parameter should not affect all user instances created before the modification.
  6. Attach/Detach volume operation should be supported irrespective of the type of disk controller of user instance. This needs to be fulfilled because a volume to be attached might have a specific type of disk controller in it's associated VMDK file which doesn't match the type of disk controller of user instance.
  7. A mix of SCSI sub-type disk controller types are not allowed in user instance. Ex: LsiLogicSAS and VmwareParavirtual scsi controllers are not allowed in single user instance.
  8. Root and data volume does not necessarily have same disk controller type. Provide means to support difference disk controllers for root and data volumes of user instance.
  9. Quality risks (test guidelines). Here are some test cases to be covered.

    1. Deploy VM when global configuration parameter "vmware.root.disk.controller" is NOT set to osdefault.

      1. Try Stop and Start the VM and verify
      2. Try restore VM operation and then start the VM and verify
    2. Attach a fresh (not yet implemented) volume to VM deployed in test case (1)
    3. Attach an old volume (which is detached from another VM) to VM deployed in test case (1)
      1. Try the same case with an old volume which have used storage controller different from the VM's SCSI storage controller. Check VM's settings to see the type of SCSI controller type.
    4. Try test case (1) through (4) with global configuration parameter "vmware.root.disk.controller" is set to osdefault.
    5. Test the following cases with global configuration parameter "vmware.root.disk.controller" is set to osdefault.,
      1. Attach a fresh volume to legacy user instance
      2. Restore a legacy user instance and try starting it.
      3. Stop and start the user instance created in step (1)
  10. Unsupported case: (What is NOT supported?)
    1. Mix of SCSI controller types in single user instance.
  11. Supportability characteristics:
    • Management server log would be written with messages indicating the type of controller used while attaching a virtual disk / volume to a user instance.
    • To debug the issues specific to this feature, administrator should check following,
      • User instance's disk configuration settings using vSphere client.
      • VMDK header/meta file that describes the virtual disk's configuration
      • Log file /var/log/cloudstack/management/management-server.log in management server
      • Log file /var/log/cloud/cloud.out  in SSVM
  12. Deployment requirements (fresh install vs. upgrade) if any
    • This feature is supported in fresh install as well as upgrade.
  13. Interoperability and compatibility requirements:
  14. Limitations
    1. Maximum SCSI virtual disks supported per user instance is 15.
  15. Target user details
    • This feature is mainly targeted for administrators

Arhitecture and Design description

  • StartCommand would modified to implement the specific controller and associate the virtual disks of instance with specific controller.
  • AttachCommand would be modified have one more field "diskController" to specify the disk controller to use while attaching volume to instance.

  • attachVolume() in VmwareStorageProcessor would be enhanced to use diskController field in AttachCommand and would attach volume to designated disk controller.
  • When registering a template need to allow the selection of the scsi controller type. If the template's OS recommends OR already installed with a particular controller then there should be a way to specify that. All the instances that would get deployed from this template should use this controller to attach the volumes. Template level setting is supported for both ROOT volumes as well as DATA volumes.
  • While registering a template, user can specify 2 optional parameters that would help control the controller type of VM's volumes during deployment.
Sl.No.Param Name Possible Values
1rootDiskControllerpvscsi, lsilogic, lsilogicsas, buslogic, osdefault, ide
2dataDiskController pvscsi, lsilogic, lsilogicsas, buslogic, osdefault, ide
  •  The existing global configuration parameter "VMware.root.disk.controller" would support one more choice (apart from currently supported 2 possible values i.e. IDE / SCSI) "osdefault" which tells CloudStack to automatically detect the controller recommended for specific guest operating system of VM being deployed. This makes administrator job automatic.
  • There is no global configuration parameter for data volumes.
  • Template level setting overrides the global configuration parameter setting.
  • Choice of controllers is not applicable for system VMs. They would use LSI Logic Parallel SCSI controller always. This is because that is recommended for OS of system VM's (Debian) running in VMware ESXi environment.
  • Legacy user instances would use the existing controller for root/data volumes. 
  • When a instance is stopped and started, then detect the controller type of existing volumes using the bus information in database.
  • If user resets instance and then try to start instance he existing bus info would be lost. Hence existing disk info is not available to depend on. Also if global configuratoin parameter "VMware.root.disk.controller" is modified, which results in loss of previous root disk controller type, use lsilogic or generic scsi controller for ROOT disk of legacy user instances.
  • All the user instances that get deployed post this feature would persist 2 keyword parameter values in user_vm_details table to remember the controller settings for the associated VM
    • rootDiskController
    • dataDiskController 
  • While attaching a virtual disk to VM where the controller type stored in DDB of VMDK descriptor file doesn't match the controller type of data volumes of the VM, ensure the VMDK file header is edited appropriately to indicate the controller type of the VM.


Adding optional field in details parameter of registerTemplate API.

Admin user can use registerTemplate API to specify specific disk controller to be used while deploying instances from the registered template.

For example, admin would like to deploy a instances from a template of CentOS 6.3 which already has PVSCSI drivers installed. And admin want all the  all volumes (root and data) attached to the instance, which is created from this template, to use PVSCSI disk controller. Here is an example API url,



No UI changes introduced.

Admin user can use registerTemplate API to specify specific disk controller to be used while deploying instances from the registered template.


No data migration required during upgrade. The information in user_vm_details table would be used to recognize legacy user instances, i.e. absence of the 2 keyword value pairs rootDiskController and dataDiskController in the table would confirm the same.

DB Schema

No changes

Further improvements

  1. Allow mix of SCSI controller types in single user instance.
  2. Allow user instance to have more than 15 disks (allowed currently) upto maximum allowed SCSI virtual disks by required SCSI controllers.



  • No labels