QEMU-IMG Cheatsheet

Berikut merupakan cheatsheet / referensi singkat untuk seluruh perintah yang tersedia pada utilitas qemu-img, sesuai dengan sintaks resmi yang ditampilkan oleh perintah --help.

Contoh output bantuan:

$ qemu-img --help
qemu-img version 6.2.0 (Debian 1:6.2+dfsg-2ubuntu6.15)
Copyright (c) 2003-2021 Fabrice Bellard and the QEMU Project developers

usage: qemu-img [standard options] command [command options]
QEMU disk image utility

Standard Options

#

-h, --help        Menampilkan bantuan dan keluar
-V, --version     Menampilkan informasi versi dan keluar
-T, --trace       [[enable=]<pattern>][,events=<file>][,file=<file>]
                  Menentukan opsi tracing

Daftar Perintah (Command Syntax)

#

amend       Mengubah metadata image (qcow2 options, dll)
bench       Benchmark performa image
bitmap      Manajemen bitmap pada image
check       Memeriksa konsistensi dan integritas image
commit      Menggabungkan perubahan ke backing file
compare     Membandingkan dua image
convert     Mengonversi format image
create     Membuat image baru
dd          Menyalin data antar image (mirip dd)
info        Menampilkan informasi image
map         Menampilkan pemetaan blok image
measure     Mengestimasi ukuran image
snapshot    Manajemen snapshot
rebase      Mengubah backing file image
resize      Mengubah ukuran image

Contoh sintaks lengkap (ringkasan dari --help):

info [--object objectdef] [--image-opts] [-f fmt] [--output=ofmt] [--backing-chain] [-U] filename
convert [options] filename [filename2 [...]] output_filename
create [options] filename [size]
resize [options] filename [+ | -]size

Output dalam Format JSON

#

Untuk mengubah format output menjadi JSON, gunakan parameter:

--output=json

Contoh

#

$ qemu-img info cirros-0.6.2-x86_64-disk.img --output=json

Output:

{
    "virtual-size": 117440512,
    "filename": "cirros-0.6.2-x86_64-disk.img",
    "cluster-size": 65536,
    "format": "qcow2",
    "actual-size": 50466816,
    "format-specific": {
        "type": "qcow2",
        "data": {
            "compat": "1.1",
            "compression-type": "zlib",
            "lazy-refcounts": false,
            "refcount-bits": 16,
            "corrupt": false,
            "extended-l2": false
        }
    },
    "dirty-flag": false
}

Get Full Backing Chain

#

Untuk mengetahui rantai lengkap backing file dari sebuah disk image (misalnya qcow2 berlapis), gunakan opsi --backing-chain.

qemu-img info --backing-chain filename

Perintah ini akan menampilkan seluruh chain image dari top layer (head) hingga base image, sehingga memudahkan troubleshooting dan analisis dependensi image.

Convert Image

#

Anda dapat mengonversi disk image qcow2 ke berbagai format lain seperti raw, qed, vdi, vmdk, atau vhd, lalu menjalankannya pada hypervisor yang mendukung format tersebut.

Mapping Format Image

#

Contoh

#

Mengonversi image qcow2 ke format vmdk:

qemu-img convert -f qcow2 -O vmdk filename.qcow2 output_filename.vmdk

Catatan:

• Gunakan opsi -p untuk menampilkan progress.
• Untuk image besar, pastikan kapasitas storage mencukupi pada lokasi output.
• Konversi tidak mengubah isi filesystem di dalam image, hanya format container-nya.

Resize / Expand Disk Image

#

Untuk mengubah ukuran disk image, gunakan perintah resize:

qemu-img resize -f fmt filename [+ | -]size

Penjelasan

#

• +size → memperbesar ukuran disk image
• -size → memperkecil ukuran disk image

Best Practice

#

• Memperbesar disk: aman dilakukan langsung, namun tetap perlu resize filesystem di dalam VM.

• Memperkecil disk:

  1. Kecilkan partisi dan filesystem di dalam VM terlebih dahulu
  2. Pastikan tidak ada data di luar ukuran baru
  3. Jalankan qemu-img resize untuk mengecilkan image

⚠️ Selalu lakukan backup sebelum resize, terutama saat mengecilkan image. Kesalahan dalam proses ini dapat menyebabkan kehilangan data permanen.

Merge Image ke Backing File (Commit)

#

Misalkan Anda memiliki:

• head.qcow2 → image aktif (top layer)
• base.qcow2 → backing file

Jika Anda ingin menggabungkan seluruh perubahan dari head.qcow2 ke base.qcow2, gunakan perintah commit.

Ilustrasi

#

Perintah

#

qemu-img commit head.qcow2

Catatan Penting

#

• Setelah commit, seluruh perubahan di head.qcow2 akan disimpan ke base.qcow2.
• File head.qcow2 tidak lagi dibutuhkan dan biasanya dapat dihapus.
• VM harus dalam keadaan mati saat melakukan commit untuk menghindari data corruption.

Change Path of Backing File (Rebase)

#

Jika Anda memindahkan backing file base.qcow2 ke lokasi (path) yang berbeda, gunakan perintah rebase pada head.qcow2 untuk memperbarui referensi backing file agar menunjuk ke path yang baru.

qemu-img rebase -f qcow2 -u -b /path/to/base.qcow2 -F qcow2 head.qcow2

Penjelasan Opsi

#

• -b /path/to/base.qcow2 → path backing file yang baru
• -F qcow2 → format backing file
• -u → unsafe mode, hanya mengubah metadata path tanpa memindahkan data

Catatan Penting

#

• Mode -u tidak memvalidasi konsistensi data, pastikan backing file lama dan baru identik.
• VM harus dalam keadaan mati saat melakukan rebase.
• rebase hanya didukung untuk image berformat qcow2.

Collapse / Flatten All Images (Tanpa Backing File)

#

Jika perintah commit digunakan untuk menggabungkan perubahan dari head.qcow2 ke base.qcow2, maka flatten bertujuan kebalikannya: menjadikan head.qcow2 sebagai disk image mandiri tanpa backing file.

Metode: virsh blockpull

#

Untuk VM yang dikelola oleh libvirt, gunakan perintah:

virsh blockpull domname vda --wait --verbose

Perintah ini akan:

• Menarik seluruh data dari backing chain ke disk aktif
• Menghasilkan disk image tunggal tanpa ketergantungan backing file

Catatan

#

• VM dapat tetap berjalan selama blockpull, namun performa disk bisa menurun.
• Gunakan virsh domblklist domname untuk memastikan target device (vda, vdb, dll).
• Setelah selesai, backing file tidak lagi digunakan.

Internal Snapshots (QCOW2)

#

Snapshot internal disimpan di dalam file qcow2 itu sendiri (bukan file terpisah).

List Snapshot

#

qemu-img snapshot -l filename

Create Snapshot

#

qemu-img snapshot -c snapshot1 filename

Restore (Apply) Snapshot

#

qemu-img snapshot -a snapshot1 filename

Delete Snapshot

#

qemu-img snapshot -d snapshot1 filename

Catatan Penting

#

• VM harus dalam keadaan mati saat membuat, restore, atau menghapus internal snapshot.

• Internal snapshot tidak direkomendasikan untuk production:

  • sulit dikelola
  • berisiko korup
  • kurang fleksibel dibanding external snapshot

External Snapshot QCOW2 (Direkomendasikan)

#

Diagram Lifecycle Snapshot QCOW2

#

Buat External Snapshot

#

virsh snapshot-create-as \
  --domain vm01 \
  --name snap1 \
  --disk-only \
  --atomic

Hasil:

• Disk aktif menjadi vm01-snap1.qcow2
• Base image tetap utuh

Lakukan Aktivitas (Upgrade / Testing)

#

• Patch OS
• Upgrade aplikasi
• Validasi perubahan

Commit / Rollback

#

Jika sukses → Commit

virsh blockcommit vm01 vda --wait --verbose

Jika gagal → Rollback

virsh snapshot-revert vm01 snap1 --disk-only

Cleanup

#

virsh snapshot-delete vm01 snap1