Proxmox «guest agent not running»: увімкнути QEMU Guest Agent і зробити це стабільним

October 27, 2025 • February 3, 2026 • Читання: 5 хв • Views: 10

Було корисно?

Ви відкриваєте зведення VM у Proxmox, щоб зробити рутинову дію — дізнатись IP гостя, ініціювати коректне завершення роботи або зафіксувати файлову систему перед бекапом — і Proxmox відповідає еквівалентом знехту:
«guest agent not running».

Це одна з тих помилок, які виглядають як «встановіть пакет і двигайте далі», поки не дізнаєшся, що це також може означати «неправильне віртуальне обладнання», «сервіс замасковано», «відсутній драйвер Windows» або «ви поставили галочку, але забули сам агент». Виправимо це правильно, перевіримо і зробимо так, щоб не поверталося після ребутів, оновлень і клонування шаблонів.

Що Proxmox насправді має на увазі під «guest agent not running»

Proxmox VE спілкується з VM через QEMU. Щоб спілкуватися всередину гостьової ОС, QEMU використовує невеликий допоміжний сервіс, що працює в гості: QEMU Guest Agent (qemu-guest-agent у Linux, сервіс, встановлений через virtio/guest tools у Windows).

Коли Proxmox показує «guest agent not running», зазвичай це одне з наступного:

Агент не встановлено у гостьовій ОС.
Агент встановлено, але сервіс зупинено або відключено (systemd, стан служби Windows, політика, некоректні оновлення).
VM не має каналу звʼязку: пристрій virtio-serial і сокет агента недоступні для гостя.
Proxmox не налаштовано для його використання: у налаштуваннях VM вимкнено опцію «QEMU Guest Agent».
Агент працює, але не відповідає: блокує SELinux/AppArmor, застарілий вузол пристрою або завислий процес агента.

Уявіть це так: галочка Proxmox — це телефонна лінія, пакет — це сам телефон, а сервіс — це людина, що піднімає слухавку. Потрібні всі три.

Факти та контекст, які зменшують загадковість

QEMU Guest Agent існує довше, ніж терпіння багатьох команд хмарної інфраструктури. Він вже роками входить до набору інструментів для керованості віртуальних машин.
Proxmox покладається під капотом на QMP канал QEMU. Коли ви виконуєте дії через агент (наприклад shutdown), Proxmox використовує QMP для виклику команд гостевого агента.
Транспорт агента зазвичай — virtio-serial. Це не «мережева магія», тому працює навіть коли мережа гостя неправильно налаштована.
Отримання IP гостя через Proxmox часто залежить від агента. DHCP і ARP-маніпуляції ненадійні; агент — авторитетне джерело інформації про інтерфейси гостя.
Підтримка Windows історично відставала від Linux у зручності. У Linux достатньо apt install; у Windows зазвичай потрібні драйвери virtio і окремий інсталятор агента.
fsfreeze — велика причина існування агента в продакшені. Узгоджені знімки/бекапи без аплікейшн-хуків складні; агент — прагматичний компроміс.
Клоновані шаблони часто ламають це. Люди роблять «золотий образ», забувають увімкнути сервіс, а потім тисяча клонів успадковує помилку.
Агент — це не те саме, що SPICE або VNC-консоль. Доступ до консолі — це відображення; guest agent — це операційна площина управління. Плутати їх — марнувати години.

Швидкий план діагностики (перевірте 1/2/3)

Хочеться швидко отримати сигнал. Ось послідовність, яку я використовую, коли надходить on-call повідомлення «shutdown зависає» або «fsfreeze в бекапі не працює», і в UI видно «guest agent not running».

1) Перевірте, чи Proxmox увімкнув агента для цієї VM

Якщо Proxmox не експонує канал virtio-serial, гість може запускати агент цілий день — і це нічого не змінить.

2) Перевірте стан сервісу в гостьовій ОС

Встановлено ≠ увімкнено. Увімкнено ≠ працює. Працює ≠ здоровий.

3) Перевірте транспорт: пристрій virtio-serial і сокет агента

Якщо гість не бачить /dev/virtio-ports/org.qemu.guest_agent.0 (Linux) або у Windows відсутній відповідний пристрій, це проблема віртуального апаратного забезпечення/драйвера.

Лише після цих трьох перевірок я йду шукати «екзотичні» причини (SELinux denial, AppArmor, падіння агента в цикл, несумісності версій).

Практичні завдання: команди, очікуваний вивід, і рішення (12+)

Цей розділ — серцевина. Кожне завдання містить: команду, як виглядає «добре», як виглядає «погано», і яке рішення робити далі.

Task 1: На Proxmox-хості підтвердити, що в конфігурації VM увімкнено агента

cr0x@server:~$ qm config 101 | egrep -i 'agent|serial|vga|machine'
agent: 1
machine: q35
vga: serial0

Що це означає: agent: 1 — це вмикання на боці Proxmox. Якщо відсутнє або 0, Proxmox не буде робити виклики агента.

Рішення: Якщо agent: 0 або відсутнє — увімкніть (Task 2). Якщо увімкнено — переходьте до перевірок у гості (Task 5+).

Task 2: Увімкнути опцію QEMU Guest Agent у Proxmox (CLI, відтворювано)

cr0x@server:~$ qm set 101 --agent enabled=1,fstrim_cloned_disks=1
update VM 101: -agent enabled=1,fstrim_cloned_disks=1

Що це означає: Це перемикає той самий прапорець, що й чекбокс у UI. Опційний fstrim_cloned_disks=1 — це покращення якості життя для thin-provisioned сховищ (особливо після клонування).

Рішення: Після увімкнення перезавантажте VM за потреби, щоб переконатися, що порт virtio-serial зʼявився (Task 4). Потім перевірте відповідь агента (Task 3).

Task 3: Запитати Proxmox пропінгувати guest agent через QMP

cr0x@server:~$ qm agent 101 ping
{"return":{}}

Що це означає: Якщо ви отримали JSON у відповіді, QEMU може спілкуватися з агентом. Якщо ви бачите помилку на кшталт «QEMU guest agent is not running», Proxmox не може до нього дістатися.

Рішення: Якщо ping працює — повідомлення в UI може бути застарілим або проблема стосується іншої команди (наприклад fsfreeze). Якщо ping не вдається — перевіряйте сервіс і пристрій у гості (Tasks 5–8).

Task 4: Підтвердити на хості, що порт virtio-serial присутній у апаратній конфігурації VM

cr0x@server:~$ qm monitor 101 --cmd 'info chardev'
chardev: org.qemu.guest_agent.0
  backend: socket
  path: /var/run/qemu-server/101.qga

Що це означає: Це показує, що QEMU створив сокет для агента. Якщо org.qemu.guest_agent.0 не в списку — канал агента не налаштовано/не доступний.

Рішення: Якщо відсутній — повторно перевірте agent: 1 і переконайтеся, що ви перезавантажили VM після змін. Якщо присутній — зосередьтеся на внутрішній частині гостя.

Task 5: Усередині Linux-гостя переконайтесь, що пакет встановлено

cr0x@server:~$ dpkg -l | grep -E '^ii\s+qemu-guest-agent\b'
ii  qemu-guest-agent  1:8.2+dfsg-1+deb12u1  amd64  Guest-side QEMU helper daemon

Що це означає: Якщо ви бачите рядок з ii, пакет встановлено. Якщо нічого немає — пакет не встановлено.

Рішення: Якщо не встановлено — інсталюйте (Task 6). Якщо встановлено — перевірте стан сервісу (Task 7).

Task 6: Встановити агент у Debian/Ubuntu гостях

cr0x@server:~$ sudo apt-get update
Hit:1 http://deb.debian.org/debian bookworm InRelease
Reading package lists... Done

cr0x@server:~$ sudo apt-get install -y qemu-guest-agent
Reading package lists... Done
Building dependency tree... Done
The following NEW packages will be installed:
  qemu-guest-agent
Setting up qemu-guest-agent (1:8.2+dfsg-1+deb12u1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/qemu-guest-agent.service → /lib/systemd/system/qemu-guest-agent.service.

Що це означає: На дистрибутивах з systemd інсталяція зазвичай увімкне сервіс. Не довіряйте цьому без перевірки; переконайтеся.

Рішення: Перейдіть до Task 7, щоб упевнитися, що він працює і здоровий.

Task 7: Перевірити стан сервісу агента в Linux (systemd)

cr0x@server:~$ systemctl status qemu-guest-agent --no-pager
● qemu-guest-agent.service - QEMU Guest Agent
     Loaded: loaded (/lib/systemd/system/qemu-guest-agent.service; enabled; preset: enabled)
     Active: active (running) since Thu 2025-12-26 11:14:02 UTC; 2min 10s ago
   Main PID: 623 (qemu-ga)
      Tasks: 1 (limit: 18936)
     Memory: 4.1M
        CPU: 82ms

Що це означає: Потрібно бачити enabled і active (running). Якщо «disabled» — це регресуватиме після ребуту. Якщо «failed» — дивіться логи (Task 8).

Рішення: Якщо не увімкнено — увімкніть (Task 9). Якщо в стані failed — перевірте логи та вузли пристроїв.

Task 8: Прочитати логи агента, щоб побачити, чи може він відкрити virtio-порт

cr0x@server:~$ journalctl -u qemu-guest-agent -b --no-pager | tail -n 30
Dec 26 11:13:58 vm101 qemu-ga[603]: info: guest agent started
Dec 26 11:13:58 vm101 qemu-ga[603]: error: failed to open /dev/virtio-ports/org.qemu.guest_agent.0: No such file or directory
Dec 26 11:13:58 vm101 systemd[1]: qemu-guest-agent.service: Main process exited, code=exited, status=1/FAILURE
Dec 26 11:13:58 vm101 systemd[1]: qemu-guest-agent.service: Failed with result 'exit-code'.

Що це означає: Агент встановлено, systemd намагається його запустити, але virtio-порту немає всередині гостя. Це майже завжди проблема у налаштуванні апаратної частини VM у Proxmox або відсутній драйвер virtio (Windows) / проблемний модуль ядра (рідко на Linux).

Рішення: Поверніться на сторону хоста: підтвердьте agent: 1, підтвердьте, що QEMU створив сокет (Task 4), перезавантажте VM. Якщо все ще відсутній — інспектуйте пристрої гостя (Task 10).

Task 9: Увімкнути і запустити сервіс агента (а якщо треба — розблокувати)

cr0x@server:~$ sudo systemctl unmask qemu-guest-agent
Removed "/etc/systemd/system/qemu-guest-agent.service".

cr0x@server:~$ sudo systemctl enable --now qemu-guest-agent
Created symlink /etc/systemd/system/multi-user.target.wants/qemu-guest-agent.service → /lib/systemd/system/qemu-guest-agent.service.

Що це означає: unmask вирішує ситуацію «когось свідомо відключив». enable --now робить це постійним після перезавантаження та стартує сервіс негайно.

Рішення: Повторіть Task 3 з хоста. Якщо ping працює — базову проблему вирішено.

Task 10: Перевірити, чи існує пристрій virtio-ports всередині Linux-гостя

cr0x@server:~$ ls -l /dev/virtio-ports/
total 0
crw------- 1 root root 241, 0 Dec 26 11:14 org.qemu.guest_agent.0

Що це означає: Це вузол пристрою, який потрібен агенту. Якщо директорія існує, але файла немає — гість не бачить точку кінця virtio-serial.

Рішення: Якщо відсутній: підтвердіть, що агент VM увімкнено і перезавантажте гостя; перевірте зміни типу машини; перевірте, чи не міглі ви мігрувати з іншого гіпервізора з дивними пристроями. Якщо присутній: агент має змогти стартувати; якщо все ще не може відкрити — перевірте AppArmor/SELinux (Task 11).

Task 11: Шукати втручання SELinux або AppArmor (рідко, але трапляється)

cr0x@server:~$ sudo aa-status --enabled
apparmor module is loaded.
apparmor filesystem is mounted.
35 profiles are loaded.
0 profiles are in complain mode.
0 profiles are in enforce mode.

Що це означає: Якщо ви бачите профіль, що примушує правила відносно qemu-ga, це може порушити доступ до пристрою. Відмови SELinux можуть робити те саме.

Рішення: Якщо є примусове виконання і логи показують відмови — налаштуйте політику або відкорегуйте профіль агента. Не вимикайте безпеку як перший рефлекс.

Task 12: З Proxmox отримати інтерфейси гостя і підтвердити, що агент дає дані

cr0x@server:~$ qm agent 101 network-get-interfaces
{"return":[{"name":"lo","ip-addresses":[{"ip-address":"127.0.0.1","ip-address-type":"ipv4","prefix":8}],"statistics":{"rx-bytes":1200,"tx-bytes":1200}},{"name":"ens18","ip-addresses":[{"ip-address":"10.10.20.41","ip-address-type":"ipv4","prefix":24},{"ip-address":"fe80::f816:3eff:fe1b:9d2a","ip-address-type":"ipv6","prefix":64}],"statistics":{"rx-bytes":12093284,"tx-bytes":2209381}}]}

Що це означає: Це «врожай»: авторитетна інформація про інтерфейси і IP без ARP-маніпуляцій.

Рішення: Якщо це працює — «guest agent not running» вирішено. Якщо ping працює, але це не працює — агент живий, але обмежений; часто це несумісність версій або обмежені права.

Task 13: Переконатися в коректному завершенні роботи через агента (щоб не доводилось вимикати живлення)

cr0x@server:~$ qm shutdown 101 --timeout 60
VM 101 shutting down

Що це означає: З працюючим агентом Proxmox може попросити гостя про коректне завершення роботи. Без нього Proxmox може перейти до ACPI, що менш надійно залежно від ОС і конфігурації.

Рішення: Якщо VM не вимикається — перевірте обробку живлення в гості і логи агента. Якщо вимикається — припиніть використовувати «Stop» як стандартну кнопку завершення роботи.

Task 14: Протестувати fsfreeze-хуки, якщо ви залежите від узгоджених бекапів

cr0x@server:~$ qm agent 101 fsfreeze-status
{"return":"thawed"}

cr0x@server:~$ qm agent 101 fsfreeze-freeze
{"return":0}

cr0x@server:~$ qm agent 101 fsfreeze-status
{"return":"frozen"}

cr0x@server:~$ qm agent 101 fsfreeze-thaw
{"return":0}

Що це означає: Якщо freeze/thaw працює — ви можете використовувати агент для узгодженості бекапів. Якщо він повертає «command not supported», агент може бути застарілим або зібраний без підтримки.

Рішення: Якщо вам потрібні узгоджені знімки — оновіть пакет гостевого агента і переконайтесь, що файлова система гостя підтримує замороження (деякі налаштування не працюють коректно).

Task 15: У Windows-гостях перевірити наявність і стан сервісу

Windows за замовчуванням не має QEMU Guest Agent. Зазвичай його інсталюють як частину пакету virtio guest tools.

cr0x@server:~$ qm agent 202 ping
qemu agent is not running

Такий вивід сам по собі не каже, у чому проблема; він просто інформує, що Proxmox не може дістатися до агента. У Windows VM перевірте сервіс QEMU GA і наявність драйвера virtio-serial (Device Manager), потім повторіть qm agent.

Task 16: Перевірка на боці хоста: чи створюється qga сокет?

cr0x@server:~$ ls -l /var/run/qemu-server/101.qga
srw-rw---- 1 root root 0 Dec 26 11:14 /var/run/qemu-server/101.qga

Що це означає: Це UNIX-сокет, який QEMU використовує для каналу guest agent. Якщо його немає — QEMU не налаштований для надання цього каналу (або VM не запущено).

Рішення: Якщо відсутній: перевірте стан VM (qm status 101), знову перевірте agent: 1, дивіться помилки запуску в journalctl для pvedaemon/pveproxy, якщо підозрюєте проблеми обробки конфігурації.

Забезпечити стійкість: налаштування, що переживе шаблони й оновлення

Виправити сьогоднішню VM — легко. Виправити кластер наступного місяця — там якраз і гинуть продукційні системи тихо.

1) Інтегруйте агента в шаблони, а не тільки в runbook

Якщо ви будуєте шаблони (і вам слід), ставтеся до QEMU Guest Agent як до SSH: встановлений, увімкнений, перевірений. Для Linux-шаблонів:

Встановіть qemu-guest-agent
Увімкніть його (systemctl enable --now qemu-guest-agent)
Після першого завантаження під Proxmox перевірте, що вузол пристрою існує

Умова «перший запуск під Proxmox» важлива, якщо шаблон створювався в іншому гіпервізорі. Порт virtio-serial — це віртуальне апаратне забезпечення. Якщо ви збираєте образ в одному гіпервізорі, а запускаєте в іншому, можна «успішно увімкнути сервіс», який нічим не зможе говорити.

2) Не розглядайте чекбокс Proxmox як опціональні метадані

У Proxmox увімкнення агента в VM — не косметичне. Воно впливає на конфігурацію QEMU-пристроїв і на те, які команди Proxmox взагалі пробує виконувати. Впровадьте це:

Встановіть його в шаблонах перед конвертацією в template
Автоматично встановлюйте під час провізіонінгу (CLI/API)
Аудитуйте існуючі VM і виправляйте

3) Зробіть увімкнення сервісу ідемпотентним

Одиночні ручні виправлення не масштабуються. Використовуйте конфігуратор (Ansible, Salt, ваш улюблений інструмент), щоб забезпечити:

Пакет встановлений
Сервіс увімкнений і запущений
Опційно: health check, що перевіряє існування virtio-порту

Не потрібно гарного оркестрування. Потрібна нудна послідовність.

4) Слідкуйте за регресіями після оновлень і «жорсткого підсилення»

Два найпоширеніші джерела регресій:

Скрипти підсилення золотого образу, які вимикають «невідомі сервіси». Вітаю, ви тільки що відключили інтеграцію з гіпервізором.
Оновлення ОС, які змінюють systemd presets або замінюють пакети; сервіс стає disabled або бінар змінює поведінку.

Жарт №1: Команди з безпеки люблять «відключити все, що не розпізнають», поки гіпервізор не виявляє, що не може коректно вимкнути VM, і «інцидентний міст» перетворюється на групову терапію.

5) Знайте, для чого потрібен агент — і для чого ні

Агент допомагає з:

Коректним завершенням роботи/перезапуском
Звітуванням IP гостя
Заморожуванням/розморожуванням файлових систем
Хуками синхронізації часу в деяких налаштуваннях

Він не є:

Заміною для моніторингу
Віддаленою оболонкою
Чарівною панацеєю для зламаної мережі гостя

Три корпоративні історії (як команди ламали це в реальному житті)

Міні-історія 1: Інцидент через неправильне припущення

Середня компанія мігрувала з старішої платформи віртуалізації до Proxmox. Було акуратне чекліст: імпортувати диски VM, завантажити, перевірити додаток. Додатки піднялись. Всі оголосили перемогу. Потім настав перший вікно обслуговування.

Інженер експлуатації намагався коректно вимкнути партію VM для патчів хостів. Proxmox показав «guest agent not running» для неприємного підмножини. Вони знехтували і скористалися «Stop», бо був обмежений час. Це не завершення роботи; це виривання вилки.

Декілька баз даних повернулися «в порядку» після включення. Одна — ні. Вона завантажилась, але час відтворення журналу бази був болісним і аплікаційний шар почав тайм-аутитись. Постмортем мав знайомий запах: «Ми припускали, що ACPI працюватиме всюди. Ми припускали, що імпортовані VM мають ті ж інструменти. Ми припускали, що «Stop» безпечний».

Виправлення було непомітним: увімкнути агента на кожній VM, встановити його в гостях і забезпечити через автоматизацію. Також навчити людей, що «Stop» — це пожежна сокира за склом: іноді потрібна, але ніколи не за замовчуванням.

Міні-історія 2: Оптимізація, що відігралася бумерангом

Інший магазин гнався за швидшим завантаженням і «легкими образами». Вони обрізали сервіси і пакети з шаблонів, включно з усім, що звучало опційно. QEMU Guest Agent виглядав опціональним. Його прибрали.

Шаблони завантажувались швидше. Дашборд виглядав акуратно. Перші тижні були тихі. Потім бекапи почали кидати помилки періодично: команди freeze файлової системи падали на деяких VM. Система бекапів переключилась на crash-consistent знімки. Ніхто цього не помічав, бо рідко тестували відновлення (класика).

Через місяці знадобилося відновлення для пошкодженого розгортання. Відновлена VM завантажилась, але дані були неконсистентні в спосіб, типовий для crash-consistent бекапів. «Оптимізація» заощадила секунди при кожному завантаженні і вартувала дня зусиль на відновлення і багато незручних питань.

Вони повернули агента, перевірили fsfreeze для потрібних навантажень і задокументували винятки. Урок не в «ніколи не оптимізувати». Урок — «не оптимізуйте функціонал операційного контролю».

Міні-історія 3: Нудна, але правильна практика, що врятувала день

Фінансова команда працювала на кластерах Proxmox із жорстким контролем змін. Їхня практика була нудною: щотижневі аудити конфігурацій VM, примусове увімкнення агента та передобслуговувальний скрипт, що перевіряє здоровʼя агента перед патчингом хостів.

Під час рутинного циклу перезавантаження хостів одна VM вперто відмовлялася від коректного завершення роботи. Скрипт попередив про це раніше: ping агента не пройшов, але VM була іншим чином здорова. Черговий мав час розібратися, не затримуючи все вікно обслуговування.

Винуватець — оновлення гостя, що замаскувало qemu-guest-agent через локальну політику. Оскільки вони виявили це до хвилі вимкнень, виправили всередині гостя, підтвердили ping агента, і VM коректно вимкнулась.

Нічого драматичного не сталося. Ніхто не отримав оплесків на загальних зборах. Оце й суть. Нудні контролі запобігають захоплюючим аваріям.

Поширені помилки: симптом → корінь проблеми → виправлення

Ось ті, що я постійно бачу в полі. Симптоми схожі; корені — різні.

1) Симптом: UI Proxmox показує «guest agent not running» після того, як ви встановили пакет

Корінь проблеми: Параметр VM у Proxmox agent: 1 не увімкнено, тому канал virtio-serial відсутній.
Виправлення: qm set <vmid> --agent enabled=1, перезавантажте VM, потім qm agent <vmid> ping.

2) Симптом: `systemctl status qemu-guest-agent` показує «failed to open /dev/virtio-ports/…»

Корінь проблеми: Гість не бачить пристрій virtio-serial. Зазвичай агент вимкнено на боці Proxmox або гість завантажився без цього віртуального обладнання.
Виправлення: Увімкніть агента в Proxmox, перезавантажте. Підтвердіть наявність /dev/virtio-ports/org.qemu.guest_agent.0.

3) Симптом: ping агента працює, але IP відсутній у зведенні Proxmox

Корінь проблеми: Агент працює, але не надсилає мережеву інформацію (старий агент, обмежені права, особливості network manager, перейменування інтерфейсів/контейнери).
Виправлення: Використайте qm agent network-get-interfaces, щоб побачити, що відправляється; оновіть гостевий агент; забезпечте стабільну конфігурацію інтерфейсів у гості.

4) Симптом: Завершення роботи зависає, Proxmox таймаутить, потім ви тиснете «Stop»

Корінь проблеми: Агент не працює і ACPI завершення не обробляється коректно гостьовою ОС; або ОС гість нездорова.
Виправлення: Спочатку виправте агента. Якщо агент здоровий — перевірте логи завершення роботи гостя і сервіси. Використовуйте «Stop» тільки після усвідомлення можливих наслідків для файлової системи.

5) Симптом: Бекапи скаржаться на fsfreeze або працюють у crash-consistent режимі

Корінь проблеми: Агент не працює, або fsfreeze не підтримується/не працює в гості (непідтримувана файлова система, агент занадто старий, додаток утримує блокування).
Виправлення: Перевірте qm agent fsfreeze-status і freeze/thaw вручну. Оновіть агент. Виключіть навантаження, де fsfreeze ризикований, і використайте аплікейшн-орієнтовані хуки.

6) Симптом: Працює на одному вузлі, падає після live migration на інший

Корінь проблеми: Зазвичай не «залежить від вузла», але може бути повʼязано з таймінгом/гонками або різними версіями QEMU. Іноді процес агента застрягає в гості і відновлюється тільки після ребуту, а не після міграції.
Виправлення: Переконайтесь у ping агента до і після міграції. Якщо постійно ламається на певному вузлі — перевіряйте пакети QEMU на хості і хост-логи.

7) Симптом: Після «підсилення» сервіс став «masked»

Корінь проблеми: Базовий скрипт замаскував unit, щоб заборонити запуск.
Виправлення: systemctl unmask qemu-guest-agent, потім enable --now. Виправте baseline-скрипт, щоб він більше цього не робив.

Контрольні списки / послідовний план

Контрольний список A: Виправити одну VM (Linux гість) за менш ніж 10 хвилин

На Proxmox-хості: qm config <vmid> | grep -i agent → якщо не увімкнено, встановіть qm set <vmid> --agent enabled=1.
Перезавантажте VM (так, дійсно), якщо щойно увімкнули канал агента.
У гості: встановіть qemu-guest-agent через менеджер пакетів.
У гості: systemctl enable --now qemu-guest-agent.
У гості: перевірте, що ls -l /dev/virtio-ports/ показує org.qemu.guest_agent.0.
На хості: qm agent <vmid> ping і qm agent <vmid> network-get-interfaces.

Контрольний список B: Забезпечити сталість через шаблони і клонування

Оновіть базові шаблони, щоб містили встановлений і увімкнений qemu-guest-agent.
Переконайтесь, що конфіг шаблону має agent: 1.
Автоматизуйте пост-провізіонінг перевірку: на хості qm agent <vmid> ping.
Щотижневий аудит існуючих VM: помічайте відсутній agent: 1 або випадки, де ping не проходить.
Навчіть команду експлуатації, що «Stop» — не shutdown; це форсоване вимкнення.

Контрольний список C: Коли бекапи залежать від координації гостя

Для кожного класу навантаження явно вирішіть: прийнятний crash-consistent чи потрібна логіка fsfreeze/app-aware.
Протестуйте fsfreeze-freeze і fsfreeze-thaw у вікно низької активності.
Моніторте таймаути заморожування; не дозволяйте «спробі freeze» зависати бекапи нескінченно.

Питання та відповіді

1) Чи достатньо просто встановити чекбокс «QEMU Guest Agent» у Proxmox?

Ні. Це увімкне канал на стороні VM. Ви все ще маєте встановити і запустити агент всередині гостьової ОС.

2) Чи потрібно перезавантажувати після увімкнення агента в Proxmox?

Часто — так. Додавання virtio-serial endpoint — це зміна віртуального апаратного забезпечення; гості зазвичай коректно виявляють це при перезавантаженні.

3) Навіщо мені агент, якщо моя VM здається робочою?

Бо «здається робочою» — це фраза, яку ви вимовляєте до того, як вам доведеться коректно вимкнути 40 VM під час аварії хосту або зробити узгоджені бекапи.

4) Чи впливає агент на продуктивність?

Нецінно. Це невеликий демон, який очікує запитів. Якщо він використовує значний CPU — є інша проблема (напр. цикл падіння).

5) Чи можна отримати IP гостя без агента?

Інколи — через таблиці ARP або записи DHCP. Це ненадійно через VLAN, фаєрволи і мульти-NIC конфігурації. Агент — надійний метод.

6) Агент працює, але Proxmox все одно показує «не працює». В чому справа?

Зазвичай гість не бачить пристрій virtio-serial або Proxmox не увімкнув канал агента. Підтвердіть agent: 1, переконайтесь, що сокет існує, і перевірте наявність /dev/virtio-ports/… у гості.

7) Чи безпечно використовувати QEMU Guest Agent з точки зору безпеки?

Він розширює набір дій, які хост може попросити гостя виконати. Це його сенс. Якщо ви не довіряєте адміністраторам гіпервізора, у вас є ширші проблеми, ніж цей пакет.

8) Чи можна використовувати його на Windows-гостях?

Так, але це не «apt install». Потрібно встановити Windows guest agent і драйвер virtio-serial. Перевірте службу Windows і записи в Device Manager.

9) Чи потрібно вмикати fsfreeze для кожної VM?

Ні. Використовуйте там, де це дає цінність (бази даних, stateful додатки) і де ви протестували. Для деяких навантажень crash-consistent знімки прийнятні і простіші.

10) Яка найнадійніша перевірка здоровʼя?

qm agent <vmid> ping з хоста, плюс цільова команда типу network-get-interfaces. Лише ping доводить підключення, але не корисність.

Висновок: практичні кроки, які можна зробити сьогодні

Виправлення «guest agent not running» — це не героїчна інженерія. Це базова гігієна, що запобігає зайвому болю: некрасивим shutdown-ам, відсутності видимості IP і неконсистентним бекапам. Зробіть нудке. Майбутнє «я» буде менш зайняте.

Практичні кроки:

Візьміть одну уражену VM і пройдіть триаду на боці хоста: qm config → qm agent ping → перевірка qga сокета.
У гості встановіть і увімкніть агента; перевірте наявність virtio-порту.
Оновіть шаблони і провізіонінг, щоб нові VM не повторювали проблему.
Додайте щотижневий аудит: VM з agent: 0 або з помилками ping фіксуйте до вікон обслуговування.

Парафраз ідеї від Gene Kranz: «Failure isn’t an option» — це не просто слоган, це рядок в бюджеті операційної надійності, оплачений перевірками, тестами і дисципліною.

Жарт №2: Якщо ваша єдина процедура вимкнення — «Stop», у вас немає процедури — у вас підкидання монети з кращим UI.