QEMU Guest Agent (QGA, пакет qemu-guest-agent) — демон внутри виртуальной машины, который даёт гипервизору KVM/QEMU безопасный канал управления гостевой ОС. На практике он закрывает три типовые задачи админа в KVM/VDS:
graceful shutdown — корректное выключение/перезагрузка ВМ, без «обрубания питания»;
получение IP — гипервизор/панель видят адреса так, как их видит сама ОС;
fsfreeze — заморозка файловых систем перед снапшотом для консистентности на уровне ФС.
Ниже — пошаговая настройка агента в госте, проверка работы канала и готовые команды для shutdown, инвентаризации сети и сценария freeze → snapshot → thaw.
Как устроен QGA и почему без него «не то»
QGA работает через виртуальный канал (чаще всего virtio-serial): на стороне гостя демон слушает устройство или сокет, на стороне хоста QEMU/libvirt отправляет JSON-команды. Из-за этого поведение ВМ для панели и автоматизации становится предсказуемым.
Выключение без QGA часто сводится к принудительному power off, что повышает риск fsck после старта и проблем с данными при активной записи.
IP без QGA гипервизор пытается «угадать» адрес по косвенным признакам (ARP, DHCP), но в реальных конфигурациях это легко ломается: несколько интерфейсов, статическая адресация, cloud-init, VLAN.
Снапшоты без fsfreeze обычно дают краш-консистентность (как после внезапной перезагрузки). Иногда норм, но для нагруженных сервисов лучше хотя бы консистентность на уровне ФС.
Перед тем как использовать fsfreeze в проде, держите в голове два важных ограничения:
fsfreezeобеспечивает консистентность на уровне файловых систем, но не гарантирует консистентность приложений (например, СУБД).Для критичных баз обычно комбинируют: включают режим бэкапа или flush на уровне БД, затем делают fsfreeze и только потом снимают снапшот.
Воспринимайте
fsfreezeкак «страховку» от грязных файловых систем и недописанных метаданных, а не как полноценную транзакционную консистентность приложений.
Проверяем: отвечает ли агент со стороны гипервизора (libvirt)
Если у вас есть доступ к KVM-хосту и libvirt, начните с базовой проверки состояния домена:
virsh dominfo vm1
virsh domstate vm1
Ключевая проверка QGA — ping-команда:
virsh qemu-agent-command vm1 '{"execute":"guest-ping"}'
Нормальный результат — корректный JSON-ответ без ошибок. Если видите «Guest agent is not responding» или «channel not found», обычно причина одна из двух: агент не установлен или не запущен в госте, либо в конфигурации ВМ не добавлен канал агента.
Если вы разворачиваете виртуалки под проекты и хотите одинаковое поведение shutdown и снапшотов, проще стандартизировать это на уровне шаблона и сразу выдавать сервисам готовую VDS с включённым QGA.
Если канала агента нет в конфигурации ВМ
В libvirt канал QGA обычно добавляется как virtio-serial channel (в XML домена это блок <channel>). В рамках статьи не приводим «активные» XML-теги, но смысл такой: на хосте создаётся unix-сокет, который мапится внутрь гостя как virtio-port устройство.
На большинстве KVM-шаблонов и панелей канал уже включён «из коробки». Если нет — корректнее включать его на стороне гипервизора или шаблона, а не пытаться «чинить» это внутри ОС.
Чтобы не разбирать каждый кейс вручную, удобный подход — держать один базовый образ с уже включённым каналом QGA и установленным агентом. Так вы получаете одинаковую диагностику и одинаковые команды управления на всём парке ВМ.
Установка QEMU Guest Agent в гостевой ОС
Внутри виртуальной машины ставим пакет и включаем systemd-сервис. Почти везде он называется одинаково: qemu-guest-agent.
Debian/Ubuntu
apt update
apt install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent
systemctl status qemu-guest-agent
RHEL/AlmaLinux/Rocky
dnf install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent
systemctl status qemu-guest-agent
Логи и быстрые признаки проблем
Если сервис активен, но с хоста не отвечает, смотрим журналы в госте:
journalctl -u qemu-guest-agent -b --no-pager
Чаще всего виновато одно из этого:
в госте не появилось устройство virtio-serial канала (демон запущен, но «подключаться некуда»);
демон не стартует автоматически (в сильно урезанных образах, без systemd);
после клонирования образа сервис отключён или замаскирован.
Graceful shutdown и reboot через QGA
Самый практичный сценарий — корректно выключить или перезагрузить ВМ перед обслуживанием хоста, миграцией или бэкапом. С QGA это выглядит как нормальная команда выключения изнутри ОС, а не «power off».
Через libvirt
Иногда достаточно штатной команды (если libvirt настроен использовать агент):
virsh shutdown vm1
Чтобы задействовать QGA наверняка, отправьте команду напрямую:
virsh qemu-agent-command vm1 '{"execute":"guest-shutdown"}'
Перезагрузка через агент:
virsh qemu-agent-command vm1 '{"execute":"guest-shutdown","arguments":{"mode":"reboot"}}'
Что считать успешным «мягким» выключением
systemd успевает корректно остановить сервисы;
файловые системы размонтируются чисто (без «recovery after crash» при следующем старте);
в логах нет признаков внезапного отключения питания.
Как получить IP-адреса ВМ через QGA
Главная команда — guest-network-get-interfaces. Она возвращает интерфейсы, MAC и IP-адреса (IPv4/IPv6), которые видит гостевая ОС:
virsh qemu-agent-command vm1 '{"execute":"guest-network-get-interfaces"}'
Вывод — JSON, удобно фильтровать его на хосте. Пример: вытащить только IPv4-адреса:
virsh qemu-agent-command vm1 '{"execute":"guest-network-get-interfaces"}' | jq -r '..|.ip_addresses? // empty | .[]? | select(.ip_address_type=="ipv4") | .ip_address'
Если в автоматизации вы выбираете «основной» интерфейс по маршруту по умолчанию или ждёте сетевую готовность после старта ВМ, удобно дополнять это таймерами systemd. По теме может пригодиться материал: cron vs systemd timers: как перевести задачи на таймеры.
Почему IP «не тот», хотя агент работает
вы фильтруете не тот тип адреса (ищете IPv4, а в ответе только IPv6);
несколько сетей или интерфейсов, а вам нужен конкретный (исключайте
lo, выбирайте по MAC или по дефолтному маршруту);после старта ВМ сеть ещё не поднялась (DHCP/NetworkManager/networkd не завершили конфигурацию).
Fsfreeze: консистентные снапшоты (freeze → snapshot → thaw)
Команды QGA для заморозки:
guest-fsfreeze-freeze— заморозить файловые системы (запись будет блокироваться);guest-fsfreeze-thaw— разморозить;guest-fsfreeze-status— проверить состояние (frozen/thawed).
Типовой сценарий на хосте
Сам принцип всегда один: сначала freeze, затем моментальный снимок, затем thaw:
virsh qemu-agent-command vm1 '{"execute":"guest-fsfreeze-freeze"}'
virsh snapshot-create-as vm1 snap1 "fsfreeze snapshot" --disk-only --atomic
virsh qemu-agent-command vm1 '{"execute":"guest-fsfreeze-thaw"}'
Опции снапшота зависят от хранилища (qcow2, LVM, Ceph и т.д.). Даже если вы делаете снимок не через libvirt, а средствами хранилища, порядок действий сохраняется: QGA freeze перед операцией и thaw сразу после.
Таймауты и защита от «вечной заморозки»
Самая неприятная авария — вы заморозили ФС и не разморозили из-за ошибки в автоматизации. Минимальный набор страховок:
перед freeze проверяйте, что статус
thawed;после freeze задавайте короткий дедлайн на создание снапшота;
в обработчике ошибок всегда выполняйте thaw.
Проверка статуса:
virsh qemu-agent-command vm1 '{"execute":"guest-fsfreeze-status"}'
Если вы предоставляете виртуалки клиентам или командам разработки, заранее продумайте, где будут храниться снапшоты и как быстро они создаются. На практике стабильнее, когда ВМ живут на предсказуемом тарифе и ресурсах, а сами бэкапы снимаются по единому регламенту.
systemd и qemu-guest-agent: проверки для надёжности
На системах с systemd обычно достаточно включить сервис, но в реальной эксплуатации полезно иметь короткий набор команд для диагностики:
systemctl is-enabled qemu-guest-agent
systemctl status qemu-guest-agent
journalctl -u qemu-guest-agent -b --no-pager
Если вы делаете кастомные образы, логичный шаг — включить QGA в базовый шаблон. Тогда graceful shutdown, инвентаризация IP и fsfreeze будут работать одинаково на всём парке виртуалок.
Типовые проблемы и быстрые решения
Агент установлен, но «не отвечает» с хоста
проверьте, что у ВМ действительно есть канал QGA на стороне гипервизора;
проверьте логи в госте:
journalctl -u qemu-guest-agent -b;убедитесь, что сервис не замаскирован:
systemctl is-enabled qemu-guest-agent.
fsfreeze «висит» или занимает слишком много времени
слишком активная запись на диск: переносите снапшоты на менее нагруженное окно;
оптимизируйте саму операцию снапшота (чем она быстрее, тем меньше эффект «подвисания» приложений);
в автоматизации обязательно делайте thaw в обработчике ошибок.
IP возвращается, но не подходит для подключения
фильтруйте по типу адреса (ipv4/ipv6) и исключайте
lo;если сетей несколько, определяйте «основную» по дефолтному маршруту уже внутри гостя, а QGA используйте как источник инвентаризации.
Итоги
QEMU Guest Agent — маленькая деталь, которая заметно повышает управляемость KVM/VDS: корректные выключения, понятная инвентаризация IP и возможность делать более предсказуемые снапшоты через fsfreeze. Если вы строите бэкапы на основе снапшотов, QGA — практический минимум, который стоит включить в стандартный образ ВМ.
Следующий шаг после внедрения — протестировать восстановление из снапшота на отдельной виртуалке и зафиксировать стандартный сценарий freeze → snapshot → thaw в вашей автоматизации.
