This feature allows the sending of arbitrary additional VM configurations to user VMs on CloudStack and is supported by KVM, XenServer and VMware hypervisors.

The administrator enables or disables this feature by the global configuration  ‘enable.additional.vm.configuration’ which is disabled by default. To add a second layer of security, the administrator must explicitly set a comma-separated list of allowed VM additional configurations per hypervisor that users can use. This is achieved by the following global settings:

  • ‘allow.additional.vm.configuration.list.kvm’
  • ‘allow.additional.vm.configuration.list.vmware’
  • ‘allow.additional.vm.configuration.list.xen’

This means that users can send additional configuration to VMs on start or update, only if:

  • The administrator has set the feature on, and
  • The administrator has set the list of allowed additional configurations and the configurations that the user wants to send to their VMs is a subset of that list

A user can send additional configurations to their VMs by setting the parameter ‘extraconfig’ on the deployVirtualMachine and updateVirtualMachine APIs. There is currently no support in the UI for this feature.

KVM hypervisor

Additional VM configurations are added as parts of XML which are appended to the XML domain of the VM. However, CloudStack needs the XML to be URL UTF-8 encoded to be accepted as a valid ‘extraconfig’ parameter. Each XML tag must be part of the comma-separated list in the global configuration: ‘allow.additional.vm.configuration.list.kvm’

Example:

If a user would like to pass this XML configuration to its VM:

<memoryBacking>

<hugepages />

</memoryBacking >

Then the following steps are needed:

  • The user must encode the string above, resulting in the string:
    “%3CmemoryBacking%3E%0D%0A++%3Chugepages%2F%3E%0D%0A%3C%2FmemoryBacking%3E”
  • Set the ‘extraconfig’ parameter on deployVirtualMachine or updateVirtualMachine API to the encoded string
  • The administrator must have previously allowed the configurations: ‘memoryBacking’ and ‘hugepages’ by the global setting ‘additional.vm.configuration.list.kvm’

VMware hypervisor

CloudStack expects a set of URL UTF-8 encoded pairs of keys and values, in the format key=value. These key-value pairs are appended to the VM configuration .vmx file.

Example:

If a user would like to pass the following key-pair configuration to its VM:

hypervisor.cpuid.v0 = “FALSE

Then the following steps are needed:

  • The user must encode the string above, resulting in the string: “hypervisor.cpuid.v0%3DFALSE”
  • Set the ‘extraconfig’ parameter on deployVirtualMachine or updateVirtualMachine API to the encoded string
  • The administrator must have previously allowed the configurations: ‘hypervisor.cpuid.v0’ by the global setting ‘allow.additional.vm.configuration.list.vmware’

XenServer hypervisor

CloudStack also expects a set of URL UTF-8 key-value pairs which will be applied to the XAPI vm-param-set.

Example:

If a user would like to pass the following key-pair configurations to its VM:

HVM-boot-policy=

PV-bootloader=pygrub

PV-args=hvc0

Then the following steps are needed:

  • The user must encode the string above, resulting in the string: ‘HVM-boot-policy%3D%0APV-bootloader%3Dpygrub%0APV-args%3Dhvc0’
  • Set the ‘extraconfig’ parameter on deployVirtualMachine or updateVirtualMachine API to the encoded string
  • The administrator must have previously allowed the configurations: ‘HVM-boot-policy’, ‘PV-bootloader’ and ‘PV-args’ by the global setting ‘allow.additional.vm.configuration.list.xen’