qm-cloud-init

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

$ qm cloud-init [vm_id] -user=[user] -password=[password]

$ qm cloud-init [vm_id] -user=[user] -password=[password] -sshkey=[ssh_key]

$ qm cloud-init [vm_id] -hostname=[hostname]

$ qm cloud-init [vm_id] -ipconfig [ipconfig]

$ qm cloud-init [vm_id] -pre [script]

qm-cloud-init <VMID> [--hostname <name>] [--ipconfig[n] <value>] [--nameserver <ip>] [--searchdomain <domain>] [--ciuser <username>] [--cipassword <password>] [--sshkeys <keys>] [--timezone <zone>] [--meta-data <data>] [--user-data <data>] [--network-config <config>] [--force] [--debug]

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

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

--ipconfig<N> <value>
    Configures network interface N (e.g., --ipconfig0). Value format is typically 'dhcp', 'static=<ip>/<cidr>,gateway=<gw>', or 'static=<ip>/<cidr>'.

--nameserver <ip>
    Sets the DNS nameserver for the VM.

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

--ciuser <username>
    Specifies the initial non-root user to be created in the VM.

--cipassword <password>
    Sets the password for the specified --ciuser.

--sshkeys <keys>
    Provides public SSH keys to be added to the --ciuser's authorized_keys file. Can be a path to a file or literal keys.

--timezone <zone>
    Sets the system timezone inside the VM.

--meta-data <data>
    Provides custom cloud-init metadata as a YAML or JSON string.

--user-data <data>
    Provides custom cloud-init user data as a YAML or shell script string.

--network-config <config>
    Provides custom cloud-init network configuration as a YAML string. Overrides --ipconfig options.

--force
    Forces the operation, potentially overwriting existing cloud-init configurations.

--debug
    Enables debug output for troubleshooting.

The qm-cloud-init command is a utility used within the Proxmox Virtual Environment (PVE) to facilitate the configuration of virtual machines (VMs) using cloud-init.

While cloud-init is a standard industry tool for initial setup of cloud instances, qm-cloud-init specifically helps in generating and applying the necessary configuration data for VMs managed by Proxmox. It allows administrators to define various aspects of a VM's initial state, such as hostname, network configuration, user accounts, and SSH keys, without manual intervention after the VM is created.

This command is particularly useful for automating VM deployments and creating standardized virtual machine templates. By providing parameters directly via the command line, qm-cloud-init generates the required cloud-init metadata and user data, which the VM consumes on its first boot, enabling seamless provisioning and customization.

Using qm-cloud-init effectively requires the target virtual machine's image or template to have the cloud-init agent installed and enabled. If the agent is not present or not properly configured, the cloud-init settings will not be applied on boot.

Changes made with qm-cloud-init (and subsequently applied via qm set) typically require the VM to be shut down and then started for the new configuration to take effect. Simply rebooting an already running VM might not re-trigger the cloud-init process.

Care should be taken when providing sensitive information like passwords directly on the command line, as they might be exposed in shell history or process listings.

While qm-cloud-init is used for generating cloud-init configuration, these configurations are typically applied to a VM using the qm set command. For instance, after generating the configuration using qm-cloud-init, one might use qm set <VMID> --cloudinit <storage_id> to link the cloud-init drive, or directly pass parameters like qm set <VMID> --ciuser <username> which implicitly uses qm-cloud-init logic internally. The direct usage of qm-cloud-init allows for more granular control over the generated cloud-init data, potentially for debugging or custom scenarios.

qm-cloud-init emerged as part of Proxmox Virtual Environment's (PVE) efforts to streamline virtual machine provisioning and embrace standard cloud methodologies. It was introduced to simplify the creation and customization of VMs by leveraging cloud-init, which became increasingly popular for automated instance setup in cloud environments. Its development paralleled the growing demand for more robust and automated VM lifecycle management within PVE, making it easier for users to deploy pre-configured instances from templates.

qm(1), cloud-init(5), pvesh(1)