Why Every VM Admin Needs to Know qemu-img
If you run a server or a homelab, you’re likely familiar with the scenario of a sudden power outage or a host freezing up (kernel panic). Restarting the server only to see the Virtual Machine (VM) report I/O errors or hang on the boot screen is a true nightmare.
I run a Proxmox homelab cluster with 12 VMs. Once, an old SSD on my Dell server failed right when the circuit breaker tripped. As a result, the 200GB .qcow2 file for my database became “corrupt” (structural damage). If I hadn’t known how to use qemu-img, I would have had to accept losing a week’s worth of data because the latest backup was outdated.
The QCOW2 (QEMU Copy-On-Write) format is very popular on KVM and Proxmox due to its flexible snapshotting features. However, because it uses a layered storage mechanism, even a few bits written incorrectly during a system crash can make the entire virtual disk file unstable. In such cases, the qemu-img toolkit is the “surgical tool” you need to save the day.
Installing the qemu-img Tool
Most virtualization-focused Linux distributions like Ubuntu Server, Debian, or Proxmox come with this tool pre-installed. If you are using a different workstation for data recovery, install the qemu-utils package.
On Ubuntu/Debian or Proxmox:
sudo apt update && sudo apt install qemu-utils -yOn CentOS/RHEL/AlmaLinux:
sudo yum install qemu-img -yQuickly check the version using the command qemu-img --version. Newer versions usually support more efficient compression and error correction algorithms.
Workflow for Checking and Repairing QCOW2 Disks
When a VM fails to boot, the biggest mistake is trying to restart it repeatedly. This action only worsens the data corruption. Shut down the VM completely and perform the diagnostic steps below.
1. Diagnosing the Disk File
First, we need to see the general status of the file. The info command will tell you if the file is locked or contains any snapshots.
qemu-img info /var/lib/vz/images/100/vm-100-disk-0.qcow2If you see the line corrupt: true, you definitely need to start repairing it immediately.
2. Detailed Diagnosis with the Check Command
This is the most important step to determine the extent of the damage. This command scans the index tables (L1/L2 tables) of the QCOW2 file. For a 100GB disk on an SSD, this process takes about 1-2 minutes.
qemu-img check /var/lib/vz/images/100/vm-100-disk-0.qcow2The results usually fall into two scenarios:
- Leaked clusters: Minor error. These are orphaned data blocks that waste space but don’t necessarily kill the VM.
- Invalid cluster/Internal errors: Severe error. The index table is misaligned, making the OS unable to read the data.
3. Proceeding with Automatic Repair
For leaked clusters, you can use the -r leaks parameter for a safe fix. If you encounter more severe errors, use -r all. Note: Always make a backup copy before running the repair command. Patching errors can sometimes involve discarding unrecoverable data blocks.
# Fix data leaks (Safe)
qemu-img check -r leaks /path/to/disk.qcow2
# Fix all structural errors (Use with caution)
qemu-img check -r all /path/to/disk.qcow24. The Ultimate Trick: Rebuilding with the Convert Command
If check -r all still fails, try using the convert command. This method reads all remaining data and writes it to a new file with a perfect index table structure.
qemu-img convert -p -f qcow2 -O qcow2 vm-100-disk-0.qcow2 vm-100-disk-0_fixed.qcow2Parameter explanation:
-p: Displays progress as a percentage.-f qcow2: The format of the corrupted source file.-O qcow2: The format of the destination file to be created.
Practical experience shows that in 90% of cases, the new file will work smoothly. qemu-img automatically discards bad blocks and reorganizes the logical data during the conversion process.
Post-Processing Verification and Prevention
After repairing or converting, don’t celebrate just yet. Run the check command one last time on the new file.
qemu-img check /var/lib/vz/images/100/vm-100-disk-0_fixed.qcow2If you receive the message No errors were found on the image, you can breathe a sigh of relief. Now, replace the old file with the new one and start the VM.
How to Avoid Future “Rescues”?
Prevention is always cheaper than a cure. To protect your virtual disks, keep these 3 points in mind:
- Get a UPS (Uninterruptible Power Supply): This is the best investment you can make. Most QCOW2 corruption cases I’ve handled were caused by sudden power loss.
- Choose the Right Cache Mode: In Proxmox,
Write backmode offers high performance but carries higher risk. For databases, prioritizeWrite throughorDirect sync. - Don’t Just Rely on Snapshots: Snapshots are stored within the QCOW2 file itself. If the file is corrupted, the snapshots are lost too. Use Proxmox Backup Server to push backups to an external drive or the cloud.
Mastering qemu-img not only helps you save data in the nick of time but also gives you a deeper understanding of virtualization systems. If you run into any trouble during the process, feel free to leave a comment, and I’ll do my best to help.
