Proxmox

Настройка QEMU Guest Agent в Proxmox VE

Пошаговая установка и включение QEMU Guest Agent для Linux-виртуальной машины в Proxmox VE с проверкой связи и диагностикой.

QEMU Guest Agent — это служба внутри виртуальной машины, через которую Proxmox VE получает дополнительную информацию о гостевой системе и может корректнее выполнять отдельные операции.

После настройки Proxmox VE сможет:

  • получать IP-адреса гостевой ОС;
  • корректно завершать работу VM;
  • замораживать файловые системы на время backup;
  • выполнять команды через guest agent;
  • точнее отображать состояние виртуальной машины.

В этой инструкции рассматривается только установка, включение и проверка QEMU Guest Agent в Linux-виртуальной машине.

Подходит для: Proxmox VE 8 и 9
Гостевая система: Ubuntu Server и Debian
Уровень сложности: начальный
Время выполнения: около 10 минут
Требуемый доступ: права управления VM и root-доступ внутри гостевой ОС

Что будет настроено

После выполнения инструкции:

  • в VM будет установлен пакет qemu-guest-agent;
  • агент будет включён в настройках Proxmox VE;
  • служба будет запущена внутри гостевой ОС;
  • будет проверена связь между Proxmox и VM;
  • будет проверено получение IP-адресов;
  • будет проверено корректное завершение VM.

Проверка текущего состояния в Proxmox VE

Выберите виртуальную машину.

Откройте:

VM → Options

Найдите:

QEMU Guest Agent

Если указано:

Disabled

агент ещё не включён на уровне VM.

Через CLI:

qm config VM_ID |
grep '^agent'

Пример:

qm config 100 |
grep '^agent'

Если строка отсутствует, настройка не включена явно.

Проверка пакета внутри VM

Войдите в виртуальную машину.

Проверьте:

dpkg -l qemu-guest-agent

Проверьте службу:

systemctl status qemu-guest-agent --no-pager

Если пакет не установлен, команда может показать:

Unit qemu-guest-agent.service could not be found

Установка в Ubuntu или Debian

Обновите индекс пакетов:

sudo apt update

Установите агент:

sudo apt install -y qemu-guest-agent

Проверьте версию пакета:

dpkg-query -W   -f='${Package} ${Version}\n'   qemu-guest-agent

Включение службы

sudo systemctl enable qemu-guest-agent

Запустите:

sudo systemctl start qemu-guest-agent

Проверьте:

systemctl status qemu-guest-agent --no-pager

Ожидаемый статус:

active (running)

Почему служба может не запускаться сразу

QEMU Guest Agent использует виртуальный serial channel, который создаётся Proxmox VE.

Если агент ещё не включён в конфигурации VM, служба внутри гостя может ожидать устройство или завершаться с ошибкой.

Поэтому после установки нужно включить agent на стороне Proxmox VE.

Включение через веб-интерфейс

Остановите VM:

Shutdown

Откройте:

VM → Options → QEMU Guest Agent

Нажмите:

Edit

Установите:

Enabled

При наличии дополнительных параметров для базовой настройки оставьте значения по умолчанию.

Запустите VM снова.

Включение через CLI

На узле Proxmox:

qm set VM_ID   --agent enabled=1

Пример:

qm set 100   --agent enabled=1

Проверьте:

qm config 100 |
grep '^agent'

Ожидаемый результат:

agent: enabled=1

Перезапуск VM

После включения agent рекомендуется полностью перезапустить VM:

qm reboot VM_ID

Если reboot через agent ещё не работает:

qm shutdown VM_ID
qm start VM_ID

Проверьте статус:

qm status VM_ID

Проверка службы после перезапуска

Внутри VM:

systemctl status qemu-guest-agent --no-pager

Проверьте запуск при загрузке:

systemctl is-enabled qemu-guest-agent

Ожидаемый результат:

enabled

Проверьте активность:

systemctl is-active qemu-guest-agent

Ожидаемый результат:

active

Проверка связи с узла Proxmox

qm agent VM_ID ping

Пример:

qm agent 100 ping

При успешной работе команда завершится без ошибки.

Получение информации об операционной системе

qm agent VM_ID get-osinfo

Пример:

qm agent 100 get-osinfo

В ответе отображаются:

  • имя ОС;
  • версия;
  • ядро;
  • архитектура.

Получение сетевых интерфейсов

qm guest cmd VM_ID network-get-interfaces

Пример:

qm guest cmd 100 network-get-interfaces

В выводе будут:

  • имена интерфейсов;
  • MAC-адреса;
  • IPv4;
  • IPv6;
  • loopback.

Просмотр IP в веб-интерфейсе

Откройте:

VM → Summary

После успешной работы агента Proxmox VE сможет отображать IP-адреса гостевой системы.

Адрес может появиться не сразу. Подождите несколько секунд и обновите страницу.

Проверка hostname

qm agent VM_ID get-host-name

Пример:

qm agent 100 get-host-name

Ожидается hostname гостевой ОС.

Проверка времени

qm agent VM_ID get-time

Сравните время внутри VM:

date

Проверьте синхронизацию:

timedatectl

Проверка корректного shutdown

На узле Proxmox:

qm shutdown VM_ID

Проверьте:

qm status VM_ID

Ожидаемый результат после завершения:

status: stopped

Запустите снова:

qm start VM_ID

Перезагрузка через guest agent

qm reboot VM_ID

Проверьте uptime внутри VM после запуска:

uptime

Заморозка файловой системы

QEMU Guest Agent может временно замораживать файловые системы перед snapshot или backup.

Проверка вручную:

qm agent VM_ID fsfreeze-freeze

Разморозка:

qm agent VM_ID fsfreeze-thaw

Важно: не оставляйте файловую систему в замороженном состоянии. Сразу выполните fsfreeze-thaw.

Ручная проверка нужна только для диагностики.

Проверка статуса файловых систем

qm agent VM_ID get-fsinfo

Команда показывает смонтированные файловые системы, известные агенту.

Backup и QEMU Guest Agent

При backup в режиме snapshot Proxmox VE может использовать guest agent для:

  1. заморозки файловой системы;
  2. создания согласованного снимка;
  3. разморозки файловой системы.

Это повышает согласованность файловой системы, но не заменяет прикладной dump базы данных.

Для PostgreSQL, MySQL и MariaDB дополнительно используйте штатные средства backup.

Проверка настроек backup

В конфигурации VM:

qm config VM_ID

Проверьте:

agent: enabled=1

Создайте тестовый backup:

vzdump VM_ID   --storage BACKUP_STORAGE   --mode snapshot   --compress zstd

Проверьте журнал задачи.

Guest Agent и Cloud-Init

QEMU Guest Agent и Cloud-Init решают разные задачи.

Cloud-Init

Используется при первом запуске для:

  • пользователя;
  • SSH-ключа;
  • IP-адреса;
  • hostname;
  • начальной конфигурации.

QEMU Guest Agent

Работает постоянно и используется для:

  • получения IP;
  • shutdown;
  • команд из Proxmox;
  • filesystem freeze;
  • информации о гостевой ОС.

Обычно в шаблоне VM используют оба компонента.

Проверка виртуального канала

Внутри VM:

ls -l /dev/virtio-ports/

Ожидается устройство вида:

org.qemu.guest_agent.0

Проверьте:

ls -l   /dev/virtio-ports/org.qemu.guest_agent.0

Если устройство отсутствует, проверьте настройку agent в Proxmox VE и выполните полный reboot VM.

Проверка процесса

ps aux |
grep '[q]emu-ga'

Проверьте сокеты и устройства:

sudo lsof |
grep qemu-ga

Просмотр журнала агента

journalctl -u qemu-guest-agent   -n 100   --no-pager

Журнал текущей загрузки:

journalctl -u qemu-guest-agent   -b   --no-pager

В режиме реального времени:

journalctl -u qemu-guest-agent -f

Остановить:

Ctrl+C

Перезапуск службы

sudo systemctl restart qemu-guest-agent

Проверьте:

systemctl status qemu-guest-agent --no-pager

С узла:

qm agent VM_ID ping

Отключение Guest Agent

На узле:

qm set VM_ID   --agent enabled=0

Внутри VM:

sudo systemctl disable --now qemu-guest-agent

Удаление пакета:

sudo apt remove -y qemu-guest-agent

Отключать агент обычно нет необходимости.

Типичные проблемы

qm agent возвращает timeout

Проверьте внутри VM:

systemctl status qemu-guest-agent --no-pager

Проверьте на узле:

qm config VM_ID |
grep '^agent'

Выполните полный reboot VM.

Служба inactive или failed

Проверьте журнал:

journalctl -u qemu-guest-agent   -n 100   --no-pager

Проверьте устройство:

ls -l /dev/virtio-ports/

Устройство virtio-port отсутствует

Убедитесь, что agent включён в настройках VM.

Остановите и запустите VM:

qm shutdown VM_ID
qm start VM_ID

Обычный restart службы внутри гостя не создаёт отсутствующее виртуальное устройство.

Proxmox не показывает IP

Проверьте:

qm guest cmd VM_ID network-get-interfaces

Убедитесь, что:

  • агент отвечает;
  • интерфейс поднят;
  • IP назначен;
  • используется поддерживаемая гостевая ОС.

Shutdown не работает

Проверьте:

qm agent VM_ID ping

Проверьте разрешения и журнал агента.

При необходимости проверьте ACPI внутри гостевой ОС.

Backup зависает на fsfreeze

Проверьте журнал агента:

journalctl -u qemu-guest-agent -b --no-pager

Проверьте файловые системы и storage внутри VM.

Не оставляйте ручной freeze активным.

Безопасный порядок настройки

  1. Установить пакет внутри VM.
  2. Включить службу.
  3. Остановить VM.
  4. Включить agent в Proxmox VE.
  5. Запустить VM.
  6. Проверить службу.
  7. Выполнить qm agent VM_ID ping.
  8. Проверить IP и hostname.
  9. Проверить shutdown.
  10. Создать тестовый backup.

Быстрый набор команд

Внутри VM:

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

На узле Proxmox:

qm set VM_ID   --agent enabled=1

Проверка:

qm agent VM_ID ping
qm agent VM_ID get-osinfo
qm guest cmd VM_ID network-get-interfaces

Итог

После выполнения инструкции:

  • установлен qemu-guest-agent;
  • служба включена внутри Linux;
  • агент активирован в Proxmox VE;
  • проверена связь с VM;
  • получены IP-адреса и данные ОС;
  • проверено корректное завершение;
  • рассмотрено использование при snapshot backup.

QEMU Guest Agent рекомендуется устанавливать во все поддерживаемые Linux-виртуальные машины Proxmox VE.

← Предыдущая статья Добавление второго виртуального диска к VM в Proxmox VE Следующая статья → Проброс USB-устройства в виртуальную машину Proxmox VE