Integrasi QEMU Guest Agent dengan Libvirt

QEMU Guest Agent adalah daemon atau layanan yang berjalan di dalam sistem operasi tamu (guest OS) pada mesin virtual. Layanan ini menyediakan saluran komunikasi dua arah antara mesin virtual dan hypervisor host, seperti KVM, QEMU, atau Proxmox VE.

Tanpa QEMU Guest Agent, host hanya dapat melihat VM sebagai sebuah proses yang sedang berjalan. Host tidak dapat mengetahui alamat IP yang digunakan VM secara langsung, tidak dapat melakukan shutdown secara aman dari sisi hypervisor, serta memiliki keterbatasan dalam menjalankan operasi tertentu seperti backup konsisten (quiesced backup).

Komunikasi antara host dan guest dilakukan melalui kanal virtio-serial yang aman dan tidak memerlukan koneksi jaringan tambahan antara host dan mesin virtual.

Instalasi dan Konfigurasi

#

Contoh berikut menggunakan hypervisor KVM dengan Libvirt.

Konfigurasi di Sisi Host

#

Edit konfigurasi VM:

virsh edit nama-vm

Tambahkan konfigurasi berikut di dalam bagian <devices>:

<channel type="unix">
  <source mode="bind"/>
  <target type="virtio" name="org.qemu.guest_agent.0"/>
</channel>

Jika VM sedang berjalan, perangkat dapat ditambahkan secara langsung tanpa mematikan VM:

echo "<channel type='unix'><target type='virtio' name='org.qemu.guest_agent.0'/></channel>" > qemuga.xml
virsh attach-device nama-vm qemuga.xml --live --config

Instalasi di Dalam VM

#

Debian/Ubuntu

#

apt update
apt install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent

RHEL/CentOS

#

yum install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent

Test QEMU Guest Agent

#

Untuk memastikan Guest Agent telah terhubung dengan host, jalankan perintah berikut:

virsh qemu-agent-command nama-vm '{"execute":"guest-ping"}'

Jika berhasil, akan muncul output:

{ "return": {} }

Untuk melihat daftar kemampuan (capabilities) dan perintah yang didukung oleh Guest Agent, gunakan:

virsh qemu-agent-command nama-vm '{"execute":"guest-info"}'

Perintah tersebut akan menampilkan informasi mengenai status Guest Agent beserta daftar command yang tersedia dan dapat digunakan oleh host.

Fitur Libvirt yang Memanfaatkan QEMU Guest Agent

#

Libvirt tidak menyediakan API khusus untuk mengakses seluruh kemampuan QEMU Guest Agent (QGA) secara langsung. Namun, sejumlah fitur dan perintah Libvirt dapat memanfaatkan QGA secara internal untuk menjalankan operasi tertentu di dalam guest.

Mengelola Allowlist dan Blocklist QEMU Guest Agent

#

Secara default, beberapa distribusi Linux membatasi perintah QEMU Guest Agent yang dapat dijalankan melalui mekanisme allowlist. Jika Anda menemukan pesan error seperti berikut:

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-network-get-route"}'

error: internal error: unable to execute QEMU agent command 'guest-network-get-route': Command guest-network-get-route has been disabled: the command is not allowed

Artinya perintah guest-network-get-route tidak termasuk dalam daftar RPC yang diizinkan oleh konfigurasi QEMU Guest Agent.

Menambahkan Perintah ke Allowlist

#

1. Buka file konfigurasi QEMU Guest Agent.

vi /etc/sysconfig/qemu-ga

2. Tambahkan guest-network-get-route ke parameter --allow-rpcs.

FILTER_RPC_ARGS="--allow-rpcs=guest-sync-delimited,guest-sync,guest-ping,guest-get-time,guest-set-time,guest-info,guest-shutdown,guest-fsfreeze-status,guest-fsfreeze-freeze,guest-fsfreeze-freeze-list,guest-fsfreeze-thaw,guest-fstrim,guest-suspend-disk,guest-suspend-ram,guest-suspend-hybrid,guest-network-get-interfaces,guest-get-vcpus,guest-set-vcpus,guest-get-disks,guest-get-fsinfo,guest-set-user-password,guest-get-memory-blocks,guest-set-memory-blocks,guest-get-memory-block-info,guest-get-host-name,guest-get-users,guest-get-timezone,guest-get-osinfo,guest-get-devices,guest-ssh-get-authorized-keys,guest-ssh-add-authorized-keys,guest-ssh-remove-authorized-keys,guest-get-diskstats,guest-get-cpustats,guest-network-get-route,guest-get-load"

3. Restart layanan QEMU Guest Agent.

systemctl restart qemu-guest-agent

4. Verifikasi bahwa perintah telah diizinkan.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-network-get-route"}'

Contoh Perintah QEMU Guest Agent

#

Berikut beberapa contoh penggunaan QEMU Guest Agent (QGA) melalui perintah virsh qemu-agent-command.

guest-info

#

Menampilkan informasi mengenai kemampuan (capabilities) dan daftar command yang didukung oleh QEMU Guest Agent.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-info"}'

guest-ping

#

Memeriksa apakah QEMU Guest Agent aktif dan dapat merespons permintaan dari host.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-ping"}'

Jika berhasil, perintah akan mengembalikan respons:

{ "return": {} }

guest-sync

#

Menyinkronkan komunikasi antara host dan guest dengan membersihkan data yang masih tersisa pada kanal komunikasi QGA.

Perintah ini umumnya digunakan sebelum menjalankan command lain untuk memastikan respons yang diterima berasal dari permintaan terbaru.

# 1. Sinkronisasi kanal komunikasi
virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-sync","arguments":{"id":1}}'

# 2. Jalankan perintah berikutnya
virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-info"}'

guest-sync-delimited

#

Fungsinya serupa dengan guest-sync, tetapi menggunakan delimiter (0xFF) untuk menandai awal respons yang valid dari QEMU Guest Agent.

Perintah ini umumnya digunakan oleh aplikasi atau library yang berkomunikasi langsung dengan QGA.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-sync-delimited","arguments":{"id":99999}}'

guest-get-time

#

Mengambil waktu sistem dari guest dalam format Unix Epoch nanosecond.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-time"}'

Contoh output:

{
  "return": 1749123456789012345
}

guest-set-time

#

Mengatur waktu sistem di dalam guest.

Nilai time menggunakan format Unix Epoch dalam satuan nanosecond.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-set-time","arguments":{"time":1704067200000000000}}'

Jika parameter time tidak diberikan, QEMU Guest Agent akan mencoba menyinkronkan waktu guest dengan waktu host.

guest-get-osinfo

#

Menampilkan informasi sistem operasi yang berjalan di dalam guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-osinfo"}'

Contoh output:

{
  "return": {
    "name": "Rocky Linux",
    "kernel-release": "5.14.0-570.17.1.el9_6.x86_64",
    "version": "9.6 (Blue Onyx)",
    "pretty-name": "Rocky Linux 9.6 (Blue Onyx)",
    "version-id": "9.6",
    "kernel-version": "#1 SMP PREEMPT_DYNAMIC Fri May 23 22:47:01 UTC 2025",
    "machine": "x86_64",
    "id": "rocky"
  }
}

Informasi yang ditampilkan dapat berbeda tergantung sistem operasi dan versi QEMU Guest Agent yang digunakan.

guest-get-host-name

#

Menampilkan hostname yang digunakan oleh guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-host-name"}'

guest-get-users

#

Menampilkan daftar pengguna yang sedang login ke guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-users"}'

guest-get-timezone

#

Menampilkan informasi zona waktu (timezone) yang digunakan oleh guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-timezone"}'

guest-shutdown

#

Melakukan shutdown guest secara terkontrol melalui sistem operasi guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-shutdown"}'

Untuk melakukan reboot:

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-shutdown","arguments":{"mode":"reboot"}}'

Untuk mematikan guest secara langsung:

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-shutdown","arguments":{"mode":"powerdown"}}'

guest-network-get-interfaces

#

Menampilkan daftar antarmuka jaringan beserta alamat IP yang dimiliki guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-network-get-interfaces"}'

guest-get-load

#

Mendapatkan load average guest

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-load"}'

guest-get-cpustats

#

Mendapatkan statistik CPU guest

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-cpustats"}'

guest-get-vcpus

#

Menampilkan informasi vCPU yang dikenali oleh guest, termasuk status aktif atau nonaktif dari setiap CPU virtual.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-vcpus"}'

Informasi ini dapat digunakan untuk memverifikasi fitur CPU hotplug atau CPU hot-unplug yang dijalankan dari sisi host.

guest-get-memory-block-info

#

Menampilkan informasi ukuran blok memori yang digunakan oleh fitur memory hotplug pada guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-memory-block-info"}'

Output biasanya berisi ukuran blok memori yang digunakan sebagai unit dasar untuk operasi penambahan atau pengurangan memori secara dinamis.

guest-get-memory-blocks

#

Menampilkan daftar blok memori yang tersedia pada guest beserta status masing-masing blok.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-memory-blocks"}'

Informasi ini berguna untuk memantau konfigurasi memory hotplug dan mengetahui blok memori yang sedang aktif atau nonaktif.

guest-network-get-route

#

Menampilkan tabel routing yang digunakan oleh guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-network-get-route"}'

Perintah ini berguna untuk melakukan troubleshooting jaringan tanpa perlu login langsung ke dalam guest.

Contoh informasi yang dapat ditampilkan:

• Default gateway
• Route statis
• Network prefix
• Interface yang digunakan untuk setiap route

guest-get-fsinfo

#

Menampilkan informasi filesystem yang terpasang di guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-fsinfo"}'

Informasi yang ditampilkan umumnya meliputi:

• Mount point
• Jenis filesystem
• Perangkat block yang digunakan
• Informasi disk terkait

Perintah ini menjadi dasar bagi fitur Libvirt seperti virsh domfsinfo.

guest-get-disks

#

Menampilkan daftar disk yang terdeteksi oleh sistem operasi guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-disks"}'

Output dapat berisi informasi seperti:

• Nama perangkat
• Kapasitas disk
• Serial number
• Informasi partisi
• Tipe perangkat penyimpanan

Perintah ini memudahkan inventarisasi perangkat storage dari sisi host.

guest-get-diskstats

#

Menampilkan statistik I/O perangkat penyimpanan yang digunakan guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-get-diskstats"}'

Informasi yang tersedia umumnya meliputi:

• Jumlah operasi baca
• Jumlah operasi tulis
• Total byte yang dibaca
• Total byte yang ditulis
• Waktu yang digunakan untuk operasi I/O

Data tersebut dapat digunakan untuk analisis performa storage dan troubleshooting bottleneck I/O pada guest.

guest-fsfreeze-status

#

Menampilkan status filesystem guest, apakah saat ini dalam kondisi normal atau sedang dibekukan (frozen).

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-fsfreeze-status"}'

Contoh output:

{
  "return": "thawed"
}

Nilai yang mungkin dikembalikan:

• thawed — filesystem dalam kondisi normal.
• frozen — filesystem sedang dibekukan.

guest-fsfreeze-freeze

#

Membekukan seluruh filesystem yang didukung di dalam guest.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-fsfreeze-freeze"}'

Perintah ini umumnya digunakan sebelum membuat snapshot atau backup agar data yang tersimpan berada dalam kondisi konsisten (application-consistent snapshot).

Saat filesystem dibekukan, operasi penulisan (write) akan ditahan sementara hingga proses thaw dijalankan.

guest-fsfreeze-freeze-list

#

Membekukan filesystem tertentu berdasarkan mount point yang ditentukan.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-fsfreeze-freeze-list","arguments":{"mountpoints":["/","/var"]}}'

Perintah ini memungkinkan administrator membekukan hanya filesystem tertentu tanpa memengaruhi seluruh sistem.

guest-fsfreeze-thaw

#

Mengaktifkan kembali seluruh filesystem yang sebelumnya dibekukan.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-fsfreeze-thaw"}'

Perintah ini harus dijalankan setelah proses snapshot atau backup selesai.

guest-fstrim

#

Menjalankan operasi TRIM pada filesystem yang mendukung.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-fstrim"}'

Perintah ini memberi tahu perangkat penyimpanan bahwa blok data yang sudah tidak digunakan dapat dilepaskan kembali.

Manfaat penggunaan guest-fstrim antara lain:

• Mengoptimalkan performa SSD.
• Mengembalikan ruang pada storage thin-provisioned.
• Mengurangi penggunaan kapasitas pada backend storage yang mendukung discard/TRIM.

guest-suspend-disk

#

Menangguhkan (suspend) guest ke media penyimpanan (hibernate).

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-suspend-disk"}'

Seluruh isi memori akan disimpan ke disk, kemudian sistem dimatikan. Saat dinyalakan kembali, guest akan melanjutkan sesi dari kondisi sebelumnya.

guest-suspend-ram

#

Menangguhkan guest ke memori (sleep atau suspend-to-RAM).

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-suspend-ram"}'

Dalam mode ini, isi memori tetap dipertahankan di RAM sehingga proses resume berlangsung lebih cepat dibandingkan hibernasi.

guest-suspend-hybrid

#

Menjalankan mode suspend hybrid, yaitu kombinasi antara suspend-to-RAM dan suspend-to-disk.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-suspend-hybrid"}'

Pada mode ini, data disimpan ke RAM dan juga ditulis ke disk. Jika terjadi kehilangan daya, sistem masih dapat dipulihkan dari salinan yang tersimpan di disk.

Mode ini memberikan keseimbangan antara kecepatan resume dan ketahanan terhadap kegagalan daya.

guest-set-user-password

#

Mengubah kata sandi pengguna di dalam guest tanpa perlu login secara langsung ke sistem operasi.

QEMU Guest Agent mengharuskan nilai password dikirim dalam format Base64.

Menggunakan Password Teks Biasa

#

Encode password terlebih dahulu:

echo -n "PasswordBaru123" | base64

Contoh output:

UGFzc3dvcmRCYXJ1MTIz

Gunakan hasil encoding tersebut pada parameter password dan set crypted ke false.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-set-user-password","arguments":{"username":"root","password":"UGFzc3dvcmRCYXJ1MTIz","crypted":false}}'

Menggunakan Password yang Sudah Di-hash

#

Untuk meningkatkan keamanan, Anda dapat mengirim password yang sudah di-hash.

Contoh menggunakan SHA-512 ($6$) di Linux:

openssl passwd -6 "MySecretPass" | base64 -w0

Kemudian gunakan hasil Base64 tersebut dengan mengatur crypted ke true.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-set-user-password","arguments":{"username":"root","password":"<base64-hash>","crypted":true}}'

guest-ssh-get-authorized-keys

#

Menampilkan daftar SSH public key yang terdapat pada file authorized_keys milik pengguna tertentu.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-ssh-get-authorized-keys","arguments":{"username":"root"}}'

Perintah ini berguna untuk melakukan audit akses SSH dari sisi host tanpa perlu login ke guest.

guest-ssh-add-authorized-keys

#

Menambahkan satu atau lebih SSH public key ke file authorized_keys milik pengguna tertentu.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-ssh-add-authorized-keys","arguments":{"username":"root","keys":["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7... user@host"]}}'

Perintah ini memudahkan proses provisioning akses SSH secara otomatis dari host.

Beberapa public key dapat ditambahkan sekaligus dengan memasukkannya ke dalam array keys.

guest-ssh-remove-authorized-keys

#

Menghapus satu atau lebih SSH public key dari file authorized_keys milik pengguna tertentu.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-ssh-remove-authorized-keys","arguments":{"username":"root","keys":["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7... user@host"]}}'

Perintah ini berguna untuk mencabut akses SSH pengguna atau menghapus key yang sudah tidak digunakan.

guest-exec

#

Menjalankan program atau perintah di dalam guest dan mengembalikan PID proses yang dibuat.

Menjalankan Perintah Sederhana

#

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-exec","arguments":{"path":"/usr/bin/ls","arg":["-la","/tmp"]}}'

Menjalankan Perintah dan Menangkap Output

#

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-exec","arguments":{"path":"/usr/bin/cat","arg":["/etc/redhat-release"],"capture-output":true}}'

Menjalankan Shell Command

#

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-exec","arguments":{"path":"/usr/bin/bash","arg":["-c","uptime"]}}'

Contoh output:

{
  "return": {
    "pid": 12345
  }
}

PID yang dikembalikan digunakan untuk memantau status proses melalui guest-exec-status.

guest-exec-status

#

Menampilkan status proses yang sebelumnya dijalankan menggunakan guest-exec.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-exec-status","arguments":{"pid":12345}}'

Contoh output:

{
  "return": {
    "exited": true,
    "exitcode": 0,
    "signal": 0,
    "out-data": "Um9ja3kgTGludXggcmVsZWFzZSA5LjMgKEJsdWUgT25peCk=",
    "err-data": ""
  }
}

Keterangan:

• exited — status proses telah selesai atau belum.
• exitcode — kode keluar (exit code) dari proses.
• signal — sinyal yang menyebabkan proses berhenti (jika ada).
• out-data — output standar (stdout) dalam format Base64.
• err-data — output error (stderr) dalam format Base64.

Untuk membaca output:

echo "Um9ja3kgTGludXggcmVsZWFzZSA5LjMgKEJsdWUgT25peCk=" | base64 -d

guest-file-open

#

Membuka file di dalam guest dan mengembalikan file handle yang akan digunakan untuk operasi berikutnya.

Membuka File untuk Dibaca

#

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-file-open","arguments":{"path":"/etc/hostname","mode":"r"}}'

Membuka File untuk Ditulis

#

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-file-open","arguments":{"path":"/tmp/test.txt","mode":"w"}}'

Contoh output:

{
  "return": 1
}

Nilai return merupakan file handle yang digunakan pada operasi baca, tulis, atau tutup file.

guest-file-read

#

Membaca isi file yang telah dibuka menggunakan guest-file-open.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-file-read","arguments":{"handle":1}}'

Contoh output:

{
  "return": {
    "buf-datalen": 25,
    "buf-b64": "cm9ja3ktdm0xCg==",
    "eof": true
  }
}

Karena data dikembalikan dalam format Base64, lakukan decoding terlebih dahulu:

echo "cm9ja3ktdm0xCg==" | base64 -d

Contoh hasil:

rocky-vm1

guest-file-write

#

Menulis data ke file yang telah dibuka.

Isi file harus dikirim dalam format Base64.

echo -n "Hello World" | base64

Contoh output:

SGVsbG8gV29ybGQ=

Menulis data ke file:

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-file-write","arguments":{"handle":2,"buf-b64":"SGVsbG8gV29ybGQ="}}'

guest-file-seek

#

Memindahkan posisi baca atau tulis pada file yang telah dibuka.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-file-seek","arguments":{"handle":1,"offset":0,"whence":0}}'

Nilai parameter whence:

guest-file-flush

#

Memaksa data yang masih berada di buffer untuk ditulis ke media penyimpanan.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-file-flush","arguments":{"handle":2}}'

Perintah ini setara dengan operasi fsync() pada sistem operasi.

guest-file-close

#

Menutup file handle yang sebelumnya dibuka.

virsh qemu-agent-command nama-vm --cmd '{"execute":"guest-file-close","arguments":{"handle":1}}'

Menutup file setelah selesai digunakan merupakan praktik yang disarankan untuk menghindari kebocoran resource.

Contoh Script Membaca File di Guest

#

Script berikut membaca isi file /etc/os-release dari dalam guest.

# Step 1: Buka file
HANDLE=$(virsh qemu-agent-command nama-vm --cmd \
  '{"execute":"guest-file-open","arguments":{"path":"/etc/os-release","mode":"r"}}' \
  | jq '.return')

echo "File Handle: $HANDLE"

# Step 2: Baca file
ENCODED=$(virsh qemu-agent-command nama-vm --cmd \
  "{\"execute\":\"guest-file-read\",\"arguments\":{\"handle\":$HANDLE}}" \
  | jq -r '.return["buf-b64"]')

# Step 3: Decode output
echo "$ENCODED" | base64 -d

# Step 4: Tutup file
virsh qemu-agent-command nama-vm --cmd \
  "{\"execute\":\"guest-file-close\",\"arguments\":{\"handle\":$HANDLE}}"

Contoh Script Menjalankan Perintah dan Mengambil Output

#

Script berikut menjalankan perintah hostname -I di guest dan menampilkan hasilnya.

# Step 1: Jalankan perintah
PID=$(virsh qemu-agent-command nama-vm --cmd \
  '{"execute":"guest-exec","arguments":{"path":"/usr/bin/hostname","arg":["-I"],"capture-output":true}}' \
  | jq '.return.pid')

echo "PID: $PID"

# Step 2: Tunggu proses selesai
sleep 1

RESULT=$(virsh qemu-agent-command nama-vm --cmd \
  "{\"execute\":\"guest-exec-status\",\"arguments\":{\"pid\":$PID}}")

# Step 3: Decode output
echo "$RESULT" | jq -r '.return["out-data"]' | base64 -d