qm-unlink

View documentation for the original command

$ tldr qm disk unlink

qm unlink <vmid> <diskid> [OPTIONS]

<vmid>
    The unique numeric ID of the virtual machine from which to unlink the disk.

<diskid>
    The identifier of the disk to be unlinked (e.g., 'ide0', 'scsi1', 'sata0'). This corresponds to the drive slot within the VM configuration.

--delete <boolean>
    If set to '1' (true), the underlying disk image file will also be deleted from the storage along with unlinking it from the VM. Default is '0' (false).

--force <boolean>
    If set to '1' (true), attempts to force the unlinking operation even if potential issues are detected. Use with caution as it might lead to data inconsistencies. Default is '0' (false).

--skiplock <boolean>
    If set to '1' (true), the command will proceed without acquiring a lock on the VM. This can be dangerous and lead to corruption if other operations are running concurrently. Default is '0' (false).

The qm-unlink command, part of the Proxmox Virtual Environment (PVE) qm utility, is used to detach a virtual disk from a specific virtual machine's configuration. This operation removes the disk's entry from the VM's hardware settings, making it no longer accessible to the VM. It's important to note that, by default, qm-unlink only unlinks the disk configuration; it does not delete the underlying disk image file from the storage. This allows for flexible management of disk resources, such as moving a disk to another VM, re-using it later, or performing manual cleanup. To also delete the disk file, the --delete option must be explicitly used. This command is crucial for managing storage attached to virtual machines in a Proxmox environment, enabling administrators to reconfigure VM storage without permanent data loss unless intended.

1. Disk File Persistence: By default, qm-unlink only removes the disk from the VM's configuration and does not delete the actual disk image file. Use the --delete option with extreme caution, as it will permanently remove the data.

2. VM State: Ensure the virtual machine is powered off before unlinking critical disks to prevent data corruption. While some hot-plugged disks might allow unlinking while the VM is running, it's generally safer to power off.

3. Advanced Options: The --force and --skiplock options should be used only by experienced administrators who understand the potential risks, as they can lead to data loss or inconsistencies if misused.

It's crucial to understand the distinction between unlinking and deleting a disk. Unlinking (the default behavior of qm-unlink) removes the disk from the VM's configuration file (e.g., /etc/pve/qemu-server/<vmid>.conf). The actual disk image file (e.g., .qcow2, .raw) remains on the storage. Deleting, enabled by the --delete option, removes both the configuration entry and the disk image file itself. This two-step approach allows for greater control over storage resources and prevents accidental data loss.

The qm-unlink command is an integral part of the qm utility, which is the primary command-line interface for managing virtual machines within the Proxmox Virtual Environment (PVE). Proxmox VE, first released in 2007, built its virtualization capabilities on QEMU/KVM. As such, the qm tool and its subcommands, including qm-unlink, have evolved alongside PVE to provide robust disk management features necessary for enterprise-grade virtualization. Its function has remained consistent: to provide a straightforward way to manage the lifecycle of virtual disks attached to VMs.

qm(1), qm-attach(1), qm-resize(1), qm-set(1), qemu-img(1)