When supporting CloudStack environments, a recurring request from operators is the ability to customise System VMs such as Console Proxy, Secondary Storage, or Virtual Router instances. Typical requirements include installing additional packages, adjusting configuration files, applying network-specific settings, or deploying monitoring and logging agents.
Until recently, these customisations required manual changes after the System VMs were deployed or rebuilding the System VM templates themselves. Both approaches introduce operational overhead and make automation, repeatability, and scalability harder to achieve.
Starting with Apache CloudStack 4.22, operators can now define User Data for System VMs. This allows customisation to be applied automatically during deployment, aligning System VM lifecycle management with the same automation principles already used for user virtual machine instances. This article explains how to configure this feature and how it can be used in practice.
How to Customise System VMs using User Data
To customise System VMs via User Data, follow the steps below:
- Log in to CloudStack UI as the default root administrator (username: admin). This feature is intentionally restricted to the default root Administrator user for security reasons.
- Navigate to Compute > User Data Library in the left-hand menu.
- Click Register User Data.
- Register your User Data by providing:
- A name
- The script content (Ensure the User Data is created in the Root Domain).
- Save the entry and note the generated User Data ID, which will be used in the next steps.
5. Navigate to Configuration > Global Settings.
6. Search for userdata to list all User Data-related Global Settings.
7. By default, the User Data for System VMs is disabled. Enable it by setting the following Global Setting to true:
-
- userdata.enabled
8. Configure the appropriate global setting for the System VM you want to customise by specifying the User Data ID recorded earlier.
The table below lists the available settings:
| Global Setting Name | Description |
| console.proxy.vm.userdata | User Data ID for Console Proxy VMs |
| secstorage.vm.userdata | User Data ID for Secondary Storage VMs |
| virtual.router.userdata | User Data ID for Virtual Router VMs |
9. To apply the changes, destroy the existing System VMs you want to customise. CloudStack will automatically redeploy them, and the specified User Data will be applied during the new System VM startup.
Conclusion
User Data support for System VMs in CloudStack 4.22 introduces a practical and automation-friendly way to customise core infrastructure components. By applying configuration at deployment time, operators can reduce manual intervention, improve consistency across environments, and better integrate System VMs into existing operational workflows.
At the same time, this capability should be used carefully. System VMs are critical components of the CloudStack control plane, and errors in User Data scripts can impact platform stability or security. User Data should always be tested in non-production environments and kept minimal, well-documented, and version-controlled.
Used correctly, this feature closes a long-standing gap in System VM lifecycle management and brings it closer to the same automation standards expected for user workloads.
Vishesh Jindal is a software engineer at ShapeBlue. He has experience in developing and managing cloud infrastructure. He has a particular interest in databases and has worked extensively on them.
When Vishesh is not working, he enjoys watching anime, playing DOTA, or working on an open-source project.
