qm-cloudinit

Configure cloudinit settings for a specific user and set password for the user

$ qm [[clou|cloudinit]] [vm_id] -user=[user] -password=[password]

$ qm [[clou|cloudinit]] [vm_id] -user=[user] -password=[password] -sshkey=[ssh_key]

$ qm [[clou|cloudinit]] [vm_id] -hostname=[hostname]

$ qm [[clou|cloudinit]] [vm_id] -ipconfig [ipconfig]

$ qm [[clou|cloudinit]] [vm_id] -pre [script]

qm-cloudinit <vmid> [OPTIONS]

<vmid>
    The unique ID of the virtual machine to configure.

--autodeploy <boolean>
    Enable or disable automatic deployment of cloud-init configuration (default is 1 for enabled).

--cipassword <password>
    Sets the password for the specified Cloud-Init user (ciuser).

--ciuser <username>
    Specifies the username for the Cloud-Init configuration (e.g., 'root', 'ubuntu').

--force-ip-config <boolean>
    Forces Cloud-Init to configure the IP address, even if it's already configured by DHCP.

--hostname <hostname>
    Sets the hostname for the VM.

--ip <ipaddress/cidr>
    Sets the IP address and CIDR for the VM's network interface (e.g., '192.168.1.10/24').

--gw <ipaddress>
    Sets the default gateway IP address for the VM.

--nameserver <ipaddress>
    Sets the DNS nameserver IP address for the VM.

--searchdomain <domain>
    Sets the DNS search domain for the VM.

--sshkeys <path-to-public-key>
    Specifies the path to an SSH public key file to be added to the ciuser's authorized_keys.

--tags <tag1,tag2,...>
    A comma-separated list of tags to associate with the VM (used for grouping/identification).

--user-data <path-to-yaml-file>
    Path to a YAML file containing custom user-data scripts or configurations for Cloud-Init.

--network <json/yaml-string>
    Directly provides network configuration in JSON or YAML format, overriding other network options.

--template <boolean>
    Marks the VM as a Cloud-Init template, applying default Cloud-Init settings and potentially simplifying future deployments.

--ide<N> <storage:size>
    Attaches a Cloud-Init disk as an IDE device (e.g., '--ide0 local-lvm:4M'). <N> is the controller index.

--scsi<N> <storage:size>
    Attaches a Cloud-Init disk as a SCSI device (e.g., '--scsi0 local-lvm:4M'). <N> is the controller index.

--virtio<N> <storage:size>
    Attaches a Cloud-Init disk as a VirtIO device (e.g., '--virtio0 local-lvm:4M'). <N> is the controller index.

The qm-cloudinit command in Proxmox VE is a powerful utility designed to automate the initial configuration of virtual machines (VMs) using Cloud-Init. Cloud-Init is the industry standard for cross-platform cloud instance initialization, commonly used to set up cloud instances on first boot.

When applied to a Proxmox VM, qm-cloudinit injects configuration data (such as hostname, IP address, DNS settings, user accounts, SSH keys, and custom scripts) into a virtual disk image that the Cloud-Init enabled guest OS can read and apply during its boot process. This streamlines the deployment of new VMs from templates, enabling Infrastructure as Code (IaC) principles.

It allows for rapid, consistent, and reproducible VM deployments without manual intervention, making it invaluable for environments that require quick scaling or frequent provisioning of new instances. The command ensures that VMs come online with the desired network, user, and other pre-defined settings.

For qm-cloudinit to function correctly, the guest VM must be running a Cloud-Init enabled operating system (e.g., most cloud images of Ubuntu, Debian, CentOS). The VM should ideally be shut down when applying Cloud-Init configurations to ensure changes are written to the disk correctly. While some settings might apply on a running VM with qemu-guest-agent, it's generally safer and more reliable to power off the VM. The Cloud-Init disk (typically a small ISO or raw disk image) must be properly attached to the VM, usually on an IDE, SCSI, or VirtIO controller, often as the first disk.

When you use qm-cloudinit, Proxmox typically generates a small virtual CD-ROM or disk image containing the Cloud-Init configuration (metadata and user-data). This disk is then attached to the VM. The Cloud-Init daemon running within the guest OS detects this disk on boot, reads the configuration, and applies the specified settings. This method allows for a 'fire and forget' approach to VM provisioning, where the VM configures itself upon its first startup.

A common best practice in Proxmox is to create a 'Cloud-Init template'. This involves importing a clean cloud image (e.g., from Ubuntu or Debian), installing the qemu-guest-agent within it, and then configuring the VM as a template using qm-cloudinit --template 1. Future VMs can then be cloned from this template, and qm-cloudinit can be used on the cloned VMs to inject unique network settings, hostnames, and user data, making them ready for use instantly.

Cloud-Init originated with Ubuntu for use on Amazon EC2 in 2009, becoming a de facto standard for initial instance configuration across various cloud platforms. Proxmox VE, a popular open-source virtualization platform, integrated Cloud-Init support to provide a robust solution for VM templating and automated deployment. The qm-cloudinit command was developed as part of Proxmox's toolset to expose and manage these Cloud-Init capabilities directly from the hypervisor, allowing Proxmox users to leverage the power of Cloud-Init for their local VM infrastructure, mirroring the automation capabilities found in public clouds.

qm(1), cloud-init(5), qemu-ga(1)