QEMU Guest Agent Kurulumu ve Faydaları

Proxmox arayüzünde bir sanal makineye tıkladığınızda IP adresi yerine boşluk görüyor, "Shutdown" butonuna bastığınızda makine kapanmayıp zaman aşımına uğruyor ve aldığınız yedeklerin veritabanını tutarlı biçimde yakalayıp yakalamadığından emin olamıyorsanız, eksik olan tek şey QEMU Guest Agent'tır. Bu küçük ajan, hipervizör ile konuk işletim sistemi arasında bir konuşma kanalı açar; olmadığında hipervizör konuğun içinde ne olduğuna dair kördür.

Bu rehberde guest agent'ın tam olarak ne yaptığını, Linux ve Windows konuklarda nasıl kurulacağını, Proxmox tarafında hangi ayarın açılması gerektiğini ve en kritik faydası olan tutarlı yedekleme mekanizmasının nasıl işlediğini anlatacağım. Sonda da "ajanı kurdum ama hâlâ çalışmıyor diyor" durumunun tüm olası sebeplerini sıralayacağım; bu hatanın kaynağı neredeyse her zaman aynı üç yerden biridir.

Guest Agent Ne İşe Yarar#

QEMU Guest Agent (qemu-ga), konuk işletim sisteminin içinde çalışan küçük bir servistir. Hipervizörle ağ üzerinden değil, sanal bir seri port (VirtIO serial kanalı) üzerinden konuşur. Bu ayrıntı önemlidir: iletişim ağdan bağımsızdır, dolayısıyla makinenin ağı çökmüş olsa bile ajan çalışmaya devam eder ve güvenlik duvarı kuralları bu kanalı etkilemez.

Ajanın sağladığı yetenekler şunlardır:

Bu listede en çok hafife alınan madde tutarlı yedektir. Ajan olmadan alınan bir anlık görüntü, sunucunun fişini çekmiş olmanızla aynı sonucu verir: yazma önbelleğinde bekleyen veriler diske inmemiştir. Bir web sunucusu bunu genellikle atlatır, ama bir veritabanı yedeği bozuk çıkabilir. Ajan varken hipervizör, anlık görüntüyü almadan hemen önce konuğa "dosya sistemini dondur" komutu gönderir.

Linux Konuklarda Kurulum#

Linux tarafında kurulum tek satırdır; asıl önemli olan servisi etkinleştirmeyi ve Proxmox tarafındaki anahtarı açmayı unutmamaktır.

# Debian / Ubuntu
apt-get update && apt-get -y install qemu-guest-agent
systemctl enable --now qemu-guest-agent

# RHEL / Rocky / AlmaLinux
dnf -y install qemu-guest-agent
systemctl enable --now qemu-guest-agent

# Alpine
apk add qemu-guest-agent
rc-update add qemu-guest-agent default
service qemu-guest-agent start

# Durum kontrolü - "active (running)" görmelisiniz
systemctl status qemu-guest-agent --no-pager

Servis çalışıyor ama Proxmox hâlâ IP göstermiyorsa, sıra ana makine tarafındaki ayardadır. Proxmox, ajanla konuşabilmesi için makineye bir VirtIO serial cihazı eklemek zorundadır ve bu yalnızca agent seçeneği açıkken yapılır:

# 200 numaralı makinede ajanı etkinleştir
qm set 200 --agent enabled=1

# fstrim'i klonlama/geri yükleme sonrası otomatik çalıştırmak isterseniz
qm set 200 --agent enabled=1,fstrim_cloned_disks=1

# Yapılandırmayı doğrula
qm config 200 | grep agent
# agent: enabled=1

⚠️ Burada kritik bir davranış var: bu ayar makine çalışırken uygulanmaz. Sanal donanım eklendiği için makinenin tam olarak kapatılıp yeniden açılması gerekir; arayüzden "Reboot" demek yeterli olmaz, çünkü QEMU süreci ayakta kalır. Doğru yöntem qm stop/qm start ya da konuk içinden kapatıp panelden başlatmaktır. "Ajanı kurdum, ayarı açtım, hâlâ çalışmıyor" şikâyetlerinin büyük çoğunluğu tam olarak bu adımdan kaynaklanır.

Ajanın gerçekten konuştuğunu ana makineden doğrulayabilirsiniz:

# Konuğun gördüğü ağ arayüzlerini hipervizörden sor
qm agent 200 network-get-interfaces

# Konuğun sistem bilgilerini al
qm agent 200 get-osinfo
# {"kernel-release":"6.1.0-...","name":"Debian GNU/Linux",...}

Bu komutlar cevap veriyorsa kanal çalışıyor demektir. QEMU guest agent is not running hatası alıyorsanız aşağıdaki hata ayıklama bölümüne geçin.

Windows Konuklarda Kurulum#

Windows'ta ajan, VirtIO sürücü paketiyle birlikte gelir. Sürücü ISO'sunu makineye bağlayıp kurulumu oradan yaparsınız. Sıra şu şekildedir:

1. VirtIO sürücü ISO'sunu Proxmox depolamasına indirin ve makineye CD-ROM olarak bağlayın.
2. Konuk içinde ISO'yu açın, guest-agent klasörüne girin.
3. Mimarinize uygun kurulum paketini (qemu-ga-x86_64.msi) çalıştırın.
4. Hizmetler ekranında QEMU Guest Agent servisinin çalıştığını ve başlangıç türünün "Otomatik" olduğunu doğrulayın.
5. Ana makinede qm set <id> --agent enabled=1 ayarını yapıp makineyi tamamen kapatıp açın.

Windows'ta ek bir kazanç daha vardır: guest agent, VSS (Volume Shadow Copy Service) ile bütünleşerek uygulama seviyesinde tutarlı yedek alınmasını sağlar. Yani yalnızca dosya sistemi değil, VSS destekleyen uygulamalar da yedek anında tutarlı bir duruma getirilir. Bunun için kurulum sırasında VSS bileşeninin de yüklendiğinden emin olun.

Windows konuklarda disk performansı almak istiyorsanız aynı ISO'daki VirtIO depolama sürücüsünü de kurmanız gerekir; bu konudaki ayrıntılar için VirtIO sürücüleri ve disk performansı yazısına bakın.

Tutarlı Yedekleme: fsfreeze Nasıl Çalışır#

Guest agent'ın en değerli işlevi budur ve arka planda ne olduğunu bilmek, yedeklerinize ne kadar güvenebileceğinizi anlamanızı sağlar. Proxmox vzdump ile anlık görüntü modunda yedek alırken şu sırayı izler:

1. Ajana guest-fsfreeze-freeze komutu gönderilir.
2. Konuk çekirdeği tüm dosya sistemlerindeki bekleyen yazmaları diske indirir ve yeni yazmaları geçici olarak durdurur.
3. Hipervizör anlık görüntüyü alır — bu genellikle bir saniyeden kısa sürer.
4. Ajana guest-fsfreeze-thaw komutu gönderilir, yazmalar kaldığı yerden devam eder.

Sonuç, dosya sistemi açısından temiz bir görüntüdür: geri yüklediğinizde dosya sistemi denetimi (fsck) gerekmez ve yarım yazılmış dosyalar bulunmaz. Bunu elle de test edebilirsiniz:

# Ana makineden konuğun dosya sistemlerini dondur
qm agent 200 fsfreeze-freeze
qm agent 200 fsfreeze-status
# frozen

# Hemen çözün - donmuş bir sistemde disk yazan her şey bekler
qm agent 200 fsfreeze-thaw
qm agent 200 fsfreeze-status
# thawed

Bu testi üretim makinesinde yaparken dikkatli olun: donmuş durumda bırakılan bir dosya sistemi, diske yazmaya çalışan tüm süreçleri kilitler.

Önemli bir sınır: fsfreeze dosya sistemi tutarlılığı sağlar, uygulama tutarlılığı sağlamaz. Linux'ta bir PostgreSQL ya da MySQL sunucusu, dondurma anında işlem ortasında olabilir. Veritabanları kendi günlük mekanizmalarıyla bunu genellikle kurtarır ama kritik veriler için yine de veritabanının kendi mantıksal yedeğini (pg_dump, mysqldump) ayrıca almak gerekir. Yedekleme stratejisini sunucu dışına taşımak için Borg ile sunucu yedekleme yazısındaki yaklaşım guest agent yedeğinin tamamlayıcısı olarak iyi çalışır.

Şablonlara ve Otomasyona Dahil Etme#

Guest agent'ı her makinede tek tek kurmak yerine temel imajınıza koymak en verimli yoldur. Şablon hazırlarken ajanı kurup etkinleştirir, ardından makineyi temizleyip şablona dönüştürürsünüz; o şablondan üretilen her klon ajanla birlikte doğar. Şablon hazırlama akışının tamamı için Proxmox'ta VM şablonu ve klonlama yazısına bakın.

cloud-init kullanıyorsanız ajanı user-data içinde kurdurmak tek satırlık bir iştir:

#cloud-config
packages:
  - qemu-guest-agent

runcmd:
  - [systemctl, enable, --now, qemu-guest-agent]

Ana makine tarafındaki --agent enabled=1 ayarını da şablon üzerinde yaparsanız klonlar bu ayarı miras alır ve hiçbir klonda unutulmaz. Zaten çalışan makinelerde ajanı toplu olarak açmak isterseniz basit bir döngü yeterlidir:

# Ajanı kapalı olan tüm makineleri listele
for id in $(qm list | awk 'NR>1 {print $1}'); do
  qm config "$id" | grep -q "^agent:" || echo "Ajan ayarı yok: $id"
done

Bu döngü hangi makinelerde ayarın eksik olduğunu gösterir; her birini qm set <id> --agent enabled=1 ile açıp bir sonraki bakım penceresinde yeniden başlatabilirsiniz. cloud-init akışını kurarken ajanı da eklemek için cloud-init ile otomatik VM kurulumu yazısındaki user-data örneğini temel alabilirsiniz.

Sık Karşılaşılan Hatalar ve Çözümleri#

En sık tekrarlanan hata listenin ilk satırıdır ve bir kez daha vurgulamakta fayda var: --agent enabled=1 ayarı sanal donanım ekler, donanım ise ancak QEMU süreci baştan başladığında oluşur. Konuk içinden reboot demek QEMU sürecini sonlandırmaz, dolayısıyla kanal yine yoktur. Makineyi tamamen durdurup başlatın.

İkinci sık hata, ajanı kurup servisi etkinleştirmeyi unutmaktır. Bazı dağıtımlarda paket kurulduğunda servis otomatik başlamaz. systemctl is-enabled qemu-guest-agent komutu size doğrudan cevap verir.

Üçüncüsü, LXC konteynerlerinde ajan aramaktır. Konteynerler ana makinenin çekirdeğini paylaştığı için Proxmox onların dosya sistemine ve süreçlerine zaten doğrudan erişir; guest agent gibi bir köprüye ihtiyaç yoktur. Konteyner ve sanal makine arasındaki bu tür yapısal farklar için LXC mi KVM mi yazısına bakabilirsiniz.

Son olarak bir güvenlik notu: guest agent, hipervizörden konuk içinde komut çalıştırılmasına izin verebilir (guest-exec). Bu, hipervizöre erişimi olan birinin konuk içinde işlem yapabilmesi anlamına gelir. Kendi altyapınızda bu normaldir; ancak hipervizör yönetimini güvenmediğiniz bir tarafla paylaşıyorsanız bu yeteneğin farkında olun.

Sıkça Sorulan Sorular#

QEMU Guest Agent kurmak zorunlu mu#

Zorunlu değil, makine ajan olmadan da sorunsuz çalışır. Ancak ajan olmadan düzgün kapatma güvenilir olmaz, arayüzde IP göremezsiniz ve en önemlisi yedekleriniz dosya sistemi açısından tutarlı olmaz. Üretim ortamında çalışan her sanal makinede kurmanızı öneririm; maliyeti birkaç megabayt bellek, kazancı ise yedeklerinize güvenebilmektir.

Guest agent ağ bağlantısı gerektirir mi#

Hayır. İletişim ağ üzerinden değil, VirtIO seri kanalı üzerinden yapılır. Bu yüzden makinenin ağı tamamen çökmüş olsa bile hipervizör ajanla konuşmaya devam edebilir ve güvenlik duvarı kurallarının bu kanalla ilgisi yoktur. Ajanın çalışması için herhangi bir port açmanız da gerekmez.

Ajanı kurdum ama Proxmox hâlâ çalışmıyor diyor#

Neredeyse her zaman sebep, makinenin tam olarak kapatılıp açılmamasıdır. --agent enabled=1 ayarı makineye yeni bir sanal cihaz ekler ve bu cihaz ancak QEMU süreci sıfırdan başladığında oluşur; konuk içinden verilen reboot komutu bunu sağlamaz. Makineyi durdurup başlatın, sonra qm agent <id> ping ile kanalı test edin.

Guest agent yedekleri gerçekten tutarlı yapar mı#

Dosya sistemi seviyesinde evet: yedek alınmadan önce bekleyen yazmalar diske indirilir ve dosya sistemi kısa süre dondurulur, böylece görüntü temiz olur. Ancak bu, uygulama seviyesinde tutarlılık garantisi vermez — bir veritabanı işlem ortasında yakalanabilir. Kritik veriler için sanal makine yedeğinin yanında veritabanının kendi mantıksal yedeğini de almalısınız.

LXC konteynerlerinde guest agent gerekir mi#

Hayır, gerekmez ve zaten kurulamaz. Konteynerler ana makinenin çekirdeğini paylaşır; Proxmox konteynerin dosya sistemine ve süreçlerine doğrudan erişebildiği için ayrı bir iletişim köprüsüne ihtiyaç yoktur. Konteyner yedekleri de doğrudan dosya sistemi seviyesinde alınır.

Guest agent performansı etkiler mi#

Ölçülebilir bir etkisi yoktur. Ajan boşta neredeyse hiç CPU kullanmaz ve birkaç megabayt bellek tüketir. Tek gözle görülür etki, yedek alınırken dosya sisteminin bir saniyeden kısa süre dondurulmasıdır; yoğun yazma yapan bir sistemde bu an kısa bir duraklama olarak hissedilebilir. Yedek pencerenizi trafiğin düşük olduğu saatlere almak bu etkiyi tamamen ortadan kaldırır.

Kapanış#

QEMU Guest Agent, kurulumu bir dakika süren ama etkisi günlük operasyonun her yerine yayılan bir bileşendir. Aklınızda kalması gereken dört şey şunlar: ajanı konuk içinde kurup servisi etkinleştirin, ana makinede --agent enabled=1 ayarını açın, ayarı açtıktan sonra makineyi tamamen kapatıp açın ve ajanı temel şablonunuza koyup bir daha hiç düşünmeyin.

Kendi sanallaştırma altyapınızı kurup bu ayarları uçtan uca yönetmek istiyorsanız tam root erişimli VDS ve sanal sunucu paketlerimiz uygun bir zemin sunar. Yedeklerin gerçekten tutarlı alındığından ve düzenli olarak test edildiğinden emin olmak isterseniz yedekleme ve sunucu yönetimi hizmetlerimiz bu döngüyü sizin yerinize işletir.