Proxmox « l’agent invité n’est pas en cours d’exécution » : activer QEMU Guest Agent et le rendre persistant

octobre 27, 2025 • février 3, 2026 • Lecture : 22 min • Views: 11

Cet article vous a aidé ?

Vous ouvrez le résumé de la VM dans Proxmox pour une action banale — récupérer l’IP invité, demander un arrêt propre, peut‑être geler le système de fichiers avant une sauvegarde — et Proxmox vous répond par l’équivalent opérationnel d’un haussement d’épaules :
« l’agent invité n’est pas en cours d’exécution ».

C’est l’une de ces erreurs qui ressemble à « installez un paquet et passez à autre chose » jusqu’à ce que vous réalisiez qu’elle peut aussi signifier « matériel virtuel incorrect », « service masqué », « pilote Windows manquant », ou « vous avez coché la case mais oublié l’agent réel ». Réglons-le correctement, vérifions-le et assurons-nous que cela reste fixé après redémarrages, mises à jour et clonage de templates.

Ce que Proxmox entend réellement par « l’agent invité n’est pas en cours d’exécution »

Proxmox VE communique avec une VM via QEMU. Pour parler à l’intérieur du système invité, QEMU utilise un petit service d’assistance tournant dans le guest : le QEMU Guest Agent (qemu-guest-agent sur Linux, un service installé via les outils virtio/guest sur Windows).

Quand Proxmox affiche « l’agent invité n’est pas en cours d’exécution », il s’agit généralement de l’un des cas suivants :

L’agent n’est pas installé dans le système invité.
L’agent est installé mais le service est arrêté/désactivé (systemd, état du service Windows, stratégie, mises à jour cassées).
La VM n’a pas le canal de communication : le périphérique virtio‑serial et la socket de l’agent QEMU ne sont pas accessibles à l’invité.
Proxmox n’est pas configuré pour l’utiliser : le paramètre VM « QEMU Guest Agent » est désactivé dans Proxmox.
Il fonctionne, mais ne répond pas : bloqué par SELinux/AppArmor, nœud de périphérique obsolète ou processus agent coincé.

Pensez-y ainsi : la case à cocher de Proxmox est la ligne téléphonique, le paquet est le téléphone, et le service est quelqu’un qui décroche réellement. Il vous faut les trois.

Faits et contexte pour démystifier le problème

QEMU Guest Agent existe depuis bien plus longtemps que la patience de beaucoup d’équipes cloud. Il est présent depuis des années comme partie de l’effort « rendre les VMs gérables » dans les piles de virtualisation.
Proxmox s’appuie sur le canal QMP de QEMU en interne. Lorsque vous lancez des actions via l’agent (comme shutdown), Proxmox utilise QMP pour appeler les commandes du guest‑agent.
Le transport de l’agent est généralement virtio‑serial. Ce n’est pas de la « magie réseau », c’est pourquoi ça fonctionne même si le réseau invité est mal configuré.
Obtenir l’IP invité via Proxmox dépend souvent de l’agent. Les astuces DHCP et ARP sont fragiles ; l’agent fournit l’information autoritaire sur les interfaces invitées.
Le support Windows a historiquement été moins simple que Linux. Sur Linux, un simple apt install suffit souvent ; Windows nécessite généralement les pilotes virtio et un installeur séparé du guest‑agent.
fsfreeze est une grosse raison d’utiliser l’agent en production. Obtenir des snapshots/sauvegardes cohérents sans hooks applicatifs est difficile ; l’agent est un compromis pragmatique.
Les templates clonés les cassent souvent. Les équipes créent une « image golden », oublient d’activer le service, puis clonent l’erreur cent fois.
L’agent n’est pas la même chose que le console SPICE ou VNC. L’accès console est de l’affichage ; l’agent est le plan de contrôle opérationnel. Les confondre fait perdre des heures.

Mode d’intervention rapide (vérifier 1/2/3)

Vous voulez du signal rapidement. Voici la séquence que j’utilise quand une alerte indique « arrêt bloqué » ou « fsfreeze sauvegarde échoue » et que l’interface affiche « l’agent invité n’est pas en cours d’exécution ».

1) Vérifier si Proxmox a activé l’agent pour cette VM

Si Proxmox n’expose pas le canal virtio‑serial, l’invité peut tourner l’agent toute la journée sans que cela compte.

2) Vérifier l’état du service dans le système invité

Installé n’est pas activé. Activé n’est pas forcément en cours d’exécution. En cours d’exécution n’est pas forcément sain.

3) Vérifier le transport : périphérique virtio‑serial et socket de l’agent

Si l’invité ne voit pas /dev/virtio-ports/org.qemu.guest_agent.0 (Linux) ou si le périphérique Windows est manquant, vous avez un problème de matériel virtuel / pilote.

Ce n’est qu’après ces trois vérifications que je commence à chercher des causes « exotiques » (refus SELinux, profil AppArmor, boucles de crash de l’agent, incompatibilités de version).

Tâches pratiques : commandes, sorties attendues et décisions (12+)

Cette section est le cœur de l’article. Chaque tâche inclut : une commande, à quoi ressemble un « bon » résultat, à quoi ressemble un « mauvais » résultat, et quelle décision prendre ensuite.

Task 1: On the Proxmox host, confirm the VM config has the agent enabled

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

Ce que cela signifie : agent: 1 est l’activation côté Proxmox. S’il est absent ou 0, Proxmox n’essaiera pas les appels à l’agent.

Décision : Si agent: 0 ou absent, activez‑le (Task 2). S’il est activé, passez aux vérifications côté invité (Task 5+).

Task 2: Enable the QEMU Guest Agent option in Proxmox (CLI, reproducible)

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

Ce que cela signifie : Cela bascule le même interrupteur que la case de l’UI. L’option fstrim_cloned_disks=1 est une amélioration pratique pour les stockages thin‑provisioned (surtout après clonage).

Décision : Après activation, redémarrez la VM si nécessaire pour garantir la présence du port virtio‑serial (Task 4). Puis vérifiez la réactivité de l’agent (Task 3).

Task 3: Ask Proxmox to ping the guest agent via QMP

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

Ce que cela signifie : Si vous obtenez un retour JSON, QEMU peut parler à l’agent. Si vous obtenez une erreur du type « QEMU guest agent is not running », Proxmox ne peut pas l’atteindre.

Décision : Si le ping fonctionne, l’erreur dans l’UI est peut‑être obsolète ou le problème est spécifique à une autre commande (comme fsfreeze). Si le ping échoue, vérifiez le service invité et le périphérique (Tasks 5–8).

Task 4: Confirm the virtio-serial port is present in the VM hardware (host-side)

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

Ce que cela signifie : Cela montre que QEMU a créé une socket pour l’agent. Si org.qemu.guest_agent.0 n’apparaît pas, le canal de l’agent n’est pas configuré/disponible.

Décision : Si absent, revérifiez agent: 1 et assurez‑vous d’avoir redémarré la VM après les changements. S’il est présent, concentrez‑vous à l’intérieur du guest.

Task 5: Inside a Linux guest, confirm the package is installed

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

Ce que cela signifie : Si vous voyez la ligne ii, c’est installé. Si rien n’apparaît, ce n’est pas installé.

Décision : Si non installé, installez‑le (Task 6). S’il est installé, vérifiez l’état du service (Task 7).

Task 6: Install the agent on Debian/Ubuntu guests

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.

Ce que cela signifie : Sur les distributions systemd, l’installation active généralement le service. Ne vous fiez pas à cela aveuglément ; vérifiez.

Décision : Passez à la Task 7 pour confirmer qu’il tourne et qu’il est sain.

Task 7: Check the Linux agent service status (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

Ce que cela signifie : Vous voulez enabled et active (running). S’il est « disabled », il se réinitialisera au reboot. S’il est « failed », consultez les logs (Task 8).

Décision : Si non activé, activez‑le (Task 9). Si en échec, vérifiez les journaux et les nœuds de périphériques.

Task 8: Read the agent logs to see if it can open the virtio port

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'.

Ce que cela signifie : L’agent est installé, systemd tente de le lancer, mais le port virtio n’est pas présent dans l’invité. C’est presque toujours un problème de paramétrage matériel VM côté Proxmox ou un pilote virtio manquant (Windows) / un module noyau absent (rare sur Linux).

Décision : Revenez côté hôte : confirmez agent: 1, confirmez que QEMU a créé la socket (Task 4), redémarrez la VM. Si c’est toujours absent, inspectez les périphériques du guest (Task 10).

Task 9: Enable and start the agent service (and unmask if needed)

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.

Ce que cela signifie : unmask corrige la situation « quelqu’un l’a désactivé intentionnellement ». enable --now permet que cela persiste après reboot et le lance immédiatement.

Décision : Relancez la Task 3 depuis l’hôte. Si le ping fonctionne, vous avez résolu le problème de base.

Task 10: Verify the virtio-ports device exists inside the Linux guest

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

Ce que cela signifie : C’est le nœud de périphérique dont l’agent a besoin. Si le répertoire existe mais que le fichier n’existe pas, l’invité ne voit pas le point de terminaison virtio‑serial.

Décision : Si absent : confirmez que l’agent VM est activé et redémarrez l’invité ; vérifiez les modifications de type de machine ; vérifiez si vous avez migré depuis un autre hyperviseur avec des périphériques incompatibles. S’il est présent : l’agent devrait pouvoir démarrer ; si ce n’est pas le cas, vérifiez AppArmor/SELinux (Task 11).

Task 11: Look for SELinux or AppArmor interference (rare, but real)

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.

Ce que cela signifie : Si vous voyez un profil en train d’appliquer des règles contre qemu-ga, cela peut empêcher l’accès au périphérique. Les refus SELinux peuvent produire le même effet.

Décision : Si l’enforcement existe et que les logs montrent des refus, adaptez la politique ou configurez correctement le profil de l’agent. N’« éteignez » pas la sécurité comme premier réflexe.

Task 12: From Proxmox, fetch the guest network interfaces and confirm the agent is delivering data

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}}]}

Ce que cela signifie : C’est le gain : des informations autoritaires sur interfaces et IP sans les astuces ARP peu fiables.

Décision : Si cela fonctionne, le message « l’agent invité n’est pas en cours d’exécution » est résolu. Si le ping fonctionne mais que ceci échoue, votre agent est vivant mais limité — souvent une incompatibilité de version ou des permissions restreintes.

Task 13: Verify clean shutdown through the agent (so you can stop forcing power-offs)

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

Ce que cela signifie : Avec un agent fonctionnel, Proxmox peut demander un arrêt in‑guest. Sans lui, Proxmox peut se rabattre sur ACPI, moins fiable selon l’OS et la configuration.

Décision : Si la VM ne s’arrête pas, vérifiez la gestion d’alimentation du guest et les logs de l’agent. Si elle s’arrête, évitez d’utiliser « Stop » comme bouton d’arrêt par défaut.

Task 14: Test fsfreeze hooks if you rely on consistent backups

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}

Ce que cela signifie : Si freeze/thaw fonctionne, vous pouvez utiliser la cohérence pilotée par l’agent pour les sauvegardes. Si cela échoue avec « command not supported », l’agent peut être trop ancien ou compilé sans ce support.

Décision : Si vous avez besoin de snapshots cohérents, mettez à jour le paquet guest‑agent et confirmez que le système de fichiers invité supporte le gel (certaines configurations posent problème).

Task 15: On Windows guests, confirm the service exists and is running

Windows ne livre pas QEMU Guest Agent par défaut. Vous l’installez généralement via le package virtio guest tools.

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

Cette sortie seule ne dit pas ce qui cloche ; elle indique juste que Proxmox ne peut pas l’atteindre. Dans la VM Windows, validez le service QEMU GA et la présence du pilote virtio‑serial (Gestionnaire de périphériques) puis retentez qm agent.

Task 16: Host-side sanity: is the qga socket being created?

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

Ce que cela signifie : C’est la socket UNIX utilisée par QEMU pour le canal agent. Si elle n’existe pas, QEMU n’est pas configuré pour fournir le canal (ou la VM n’est pas en cours d’exécution).

Décision : Si elle manque : vérifiez l’état de la VM (qm status 101), revérifiez agent: 1, et regardez les erreurs de démarrage dans journalctl pour pvedaemon/pveproxy si vous suspectez un problème de gestion de configuration.

Rendre la solution persistante : configuration qui survive templates et mises à jour

Réparer la VM d’aujourd’hui est facile. Réparer les clones du mois prochain est là où les systèmes de production meurent en silence.

1) Bake the agent into your templates, not your runbooks

Si vous construisez des templates (et vous devriez), traitez QEMU Guest Agent comme SSH : installé, activé, validé. Pour les templates Linux :

Installer qemu-guest-agent
L’activer (systemctl enable --now qemu-guest-agent)
Vérifier l’existence du nœud de périphérique après le premier démarrage sous Proxmox

La clause « premier démarrage sous Proxmox » est importante si le template a été construit ailleurs. Le port virtio‑serial est du matériel virtuel. Si vous construisez sur un hyperviseur puis lancez sur un autre, vous pouvez « activer un service » qui n’a rien à quoi parler.

2) Don’t treat the Proxmox checkbox as optional metadata

Dans Proxmox, activer l’agent sur la VM n’est pas cosmétique. Cela impacte la configuration des périphériques QEMU et quelles commandes Proxmox tente. Faites‑le respecter :

Positionnez‑le sur les templates avant conversion en template
Activez‑le automatiquement lors du provisionnement (CLI/API)
Auditez les VMs existantes et remédiez

3) Make service enablement idempotent

Les corrections ponctuelles ne montent pas en charge. Utilisez la gestion de configuration (Ansible, Salt, votre poison) pour appliquer :

Paquet installé
Service activé et en cours
Optionnel : un contrôle de santé qui valide l’existence du port virtio

Pas besoin d’orchestration sophistiquée. Il faut de la constance ennuyeuse.

4) Watch for regressions after OS upgrades and “hardening”

Les deux sources de régression les plus courantes :

Scripts de durcissement de l’image golden qui désactivent « les services inconnus ». Félicitations, vous venez de désactiver votre intégration hyperviseur.
Mises à jour OS qui modifient les presets systemd ou remplacent des paquets ; le service passe en disabled, ou le binaire agent change de comportement.

Blague #1 : les équipes sécurité adorent « désactiver tout ce que vous ne reconnaissez pas » jusqu’à ce que l’hyperviseur ne puisse plus éteindre la VM et que la « cellule incident » devienne une thérapie de groupe.

5) Know what the agent is for—and what it isn’t

L’agent aide pour :

Arrêt/redémarrage propre
Rapport d’IP invité
Gel/dégel du système de fichiers
Hooks de synchronisation d’heure dans certaines configurations

Il n’est pas :

Un remplacement du monitoring
Une shell distante
Une solution magique pour un réseau invité cassé

Trois mini‑histoires d’entreprise (comment les équipes cassent ça en vrai)

Mini-story 1: The incident caused by a wrong assumption

Une entreprise de taille moyenne a migré d’une ancienne plateforme de virtualisation vers Proxmox. Ils avaient une checklist propre : importer les disques VM, démarrer, valider l’appli. Les applications se sont lancées. Tout le monde a crié victoire. Puis est venu le premier créneau de maintenance.

L’ingénieur ops a tenté d’arrêter proprement un lot de VMs pour patcher les hôtes. Proxmox affichait « l’agent invité n’est pas en cours d’exécution » sur un sous‑ensemble non trivial. Ils ont haussé les épaules et utilisé « Stop » parce que la fenêtre de changement se refermait. Ce n’est pas un arrêt ; c’est couper l’alimentation.

Quelques bases de données sont revenues « bien » après redémarrage. Une ne l’a pas fait. Elle a démarré, mais le replay de la base a été douloureux et la couche applicative a commencé à timeout. Le postmortem sentait la prévisibilité : « On a supposé que ACPI marcherait partout. On a supposé que les VMs importées avaient les mêmes outils invités. On a supposé que ‘Stop’ était sûr. »

La correction a été peu glamour : activer l’agent sur chaque VM, l’installer dans les guests, et l’appliquer via l’automatisation. Et apprendre aux équipes que « Stop » est la hache derrière une vitre — parfois nécessaire, jamais par défaut.

Mini-story 2: The optimization that backfired

Une autre équipe a poursuivi des améliorations de temps de boot et des images « légères ». Ils ont retiré des services et paquets des templates, y compris tout ce qui semblait optionnel. QEMU Guest Agent a semblé optionnel. Il a été retiré.

Les templates ont démarré plus vite. Le tableau de bord était propre. Les premières semaines ont été calmes. Puis les sauvegardes ont commencé à jeter des erreurs de façon intermittente : commandes fsfreeze échouaient sur certaines VMs. Le système de sauvegarde est revenu à des snapshots crash‑consistents. Personne n’a remarqué parce que les restaurations n’étaient pas testées fréquemment (classique).

Des mois plus tard, une restauration a été nécessaire pour un déploiement applicatif corrompu. La VM restaurée a démarré, mais les données étaient incohérentes exactement comme le permettent les sauvegardes crash‑consistentes. L’« optimisation » a économisé des secondes par boot et coûté une journée de récupération et beaucoup de questions gênantes.

Ils ont réintroduit l’agent, validé fsfreeze pour les charges concernées, et documenté les exceptions. La leçon n’était pas « ne jamais optimiser ». C’était « n’optimisez pas au détriment du contrôle opérationnel ».

Mini-story 3: The boring but correct practice that saved the day

Une équipe de services financiers gérait des clusters Proxmox avec un contrôle de changement strict. Leur pratique était ennuyeuse : audits hebdomadaires des configs VM, activation forcée de l’agent, et un script pré‑maintenance qui vérifiait la santé de l’agent avant le patch des hôtes.

Lors d’un cycle de redémarrage d’hôtes routinier, une VM a refusé un arrêt propre. Le script l’a signalée tôt : ping de l’agent échoué, mais la VM était autrement saine. L’astreinte a eu le temps d’enquêter sans bloquer la fenêtre de maintenance.

Le coupable était une mise à jour d’OS invité qui avait masqué le service qemu-guest-agent suite à un conflit de politique locale. Parce qu’ils l’ont détecté avant la vague d’arrêts, ils l’ont corrigé dans le guest, confirmé le ping de l’agent, et la VM s’est arrêtée proprement.

Rien de spectaculaire ne s’est produit. Personne n’a été applaudi en réunion générale. C’est le point. Les contrôles ennuyeux évitent les incidents passionnants.

Erreurs courantes : symptôme → cause racine → correction

Voici celles que je vois le plus souvent sur le terrain. Les symptômes se ressemblent ; les causes racines non.

1) Symptom: Proxmox UI shows “guest agent not running” after you installed the package

Cause racine : Le paramètre VM Proxmox agent: 1 n’est pas activé, le canal virtio‑serial n’est donc pas présent.
Correction : qm set <vmid> --agent enabled=1, redémarrez la VM, puis qm agent <vmid> ping.

2) Symptom: `systemctl status qemu-guest-agent` shows “failed to open /dev/virtio-ports/…”

Cause racine : L’invité ne voit pas le périphérique virtio‑serial. Habituellement agent désactivé côté Proxmox, ou boot sans ce matériel virtuel.
Correction : Activez l’agent dans Proxmox, redémarrez. Confirmez l’existence de /dev/virtio-ports/org.qemu.guest_agent.0.

3) Symptom: Agent ping works, but IP address is missing in Proxmox summary

Cause racine : Agent en fonctionnement mais info réseau non rapportée (agent ancien, permissions restreintes, gestionnaire réseau particulier, renommage d’interfaces/containers).
Correction : Utilisez qm agent network-get-interfaces pour voir ce qui est rapporté ; mettez à jour l’agent ; assurez une configuration d’interface stable dans l’invité.

4) Symptom: Shutdown hangs, Proxmox times out, then you hit “Stop”

Cause racine : Agent non fonctionnel et ACPI mal géré par l’OS invité ; ou OS invité en mauvais état.
Correction : Réparez l’agent en priorité. Si l’agent est sain, vérifiez les logs d’arrêt du guest et les services. Utilisez « Stop » seulement après avoir accepté le risque d’incohérence du système de fichiers.

5) Symptom: Backups complain about fsfreeze or run crash-consistent unexpectedly

Cause racine : Agent non en cours, ou fsfreeze non supporté/fonctionnel dans le guest (système de fichiers non supporté, agent trop ancien, application verrouillant).
Correction : Validez qm agent fsfreeze-status et testez freeze/thaw manuellement. Mettez à jour l’agent. Excluez les workloads risqués et utilisez des hooks applicatifs si nécessaire.

6) Symptom: Works on one node, fails after live migration to another

Cause racine : Généralement pas « spécifique au nœud », mais vous pouvez rencontrer des problèmes de timing ou de versions QEMU différentes. Parfois le processus agent dans le guest est coincé et se rétablit au reboot, pas à la migration.
Correction : Confirmez le ping de l’agent avant et après migration. Si cela casse systématiquement sur un nœud, vérifiez les paquets QEMU du nœud et les logs hôtes.

7) Symptom: After “hardening,” the service is “masked”

Cause racine : Un script de baseline a masqué l’unité pour empêcher son démarrage.
Correction : systemctl unmask qemu-guest-agent, puis enable --now. Corrigez la baseline pour qu’elle cesse de faire ça.

Checklists / step-by-step plan

Checklist A: Fix a single VM (Linux guest) in under 10 minutes

Sur l’hôte Proxmox : qm config <vmid> | grep -i agent → si non activé, définir qm set <vmid> --agent enabled=1.
Redémarrer la VM (oui, vraiment) si vous venez d’activer le canal device de l’agent.
Dans le guest : installer qemu-guest-agent via votre gestionnaire de paquets.
Dans le guest : systemctl enable --now qemu-guest-agent.
Dans le guest : vérifier que ls -l /dev/virtio-ports/ montre org.qemu.guest_agent.0.
Sur l’hôte : qm agent <vmid> ping et qm agent <vmid> network-get-interfaces.

Checklist B: Make it stick across templates and clones

Mettre à jour vos templates de base pour inclure qemu-guest-agent installé et activé.
Vérifier que la config VM du template a agent: 1.
Automatiser un contrôle post‑provisionnement : côté hôte qm agent <vmid> ping.
Auditer les VMs existantes hebdomadairement : signaler celles avec agent: 0 ou des pings échoués.
Apprendre à l’équipe ops que « Stop » n’est pas un arrêt ; c’est un arrêt forcé.

Checklist C: When backups depend on guest coordination

Pour chaque classe de workload, décider explicitement : la cohérence crash‑consistent est acceptable, ou il faut fsfreeze/logiciel applicatif.
Tester fsfreeze-freeze et fsfreeze-thaw pendant une fenêtre à faible trafic.
Surveiller les timeouts de freeze ; ne laissez pas une tentative de gel bloquer indéfiniment les sauvegardes.

FAQ

1) Is the Proxmox “QEMU Guest Agent” checkbox enough?

Non. Elle active le canal côté VM. Vous devez toujours installer et exécuter l’agent à l’intérieur du système invité.

2) Do I need to reboot after enabling the agent in Proxmox?

Souvent, oui. Ajouter l’endpoint virtio‑serial est un changement de matériel virtuel ; les guests le détectent en général proprement au redémarrage.

3) Why do I care about the agent if my VM works fine?

Parce que « ça marche » est ce qu’on dit avant d’avoir à arrêter proprement 40 VMs pendant une urgence d’hôte, ou avant d’avoir besoin de sauvegardes cohérentes.

4) Does the agent affect performance?

De façon négligeable. C’est un petit démon en attente de requêtes. S’il consomme réellement du CPU, quelque chose ne va pas (boucles de crash, etc.).

5) Can I get guest IP addresses without the agent?

Parfois, via les tables ARP ou les baux DHCP. C’est peu fiable à travers VLANs, firewalls et configurations multi‑NIC. L’agent est la méthode fiable.

6) My agent is running, but Proxmox still shows “not running.” What gives?

Généralement l’invité ne voit pas le périphérique virtio‑serial, ou Proxmox n’a pas activé le canal. Confirmez agent: 1, vérifiez l’existence de la socket et de /dev/virtio-ports/… dans le guest.

7) Is QEMU Guest Agent safe from a security perspective?

Il étend ce que l’hôte peut demander au guest. C’est le but. Si vous ne faites pas confiance aux administrateurs de l’hyperviseur, vous avez des problèmes plus larges que ce paquet.

8) Can I use it on Windows guests?

Oui, mais ce n’est pas un apt install. Vous devez installer l’agent Windows et le pilote virtio‑serial. Validez le service Windows et les entrées du Gestionnaire de périphériques.

9) Should I enable fsfreeze for every VM?

Non. Utilisez‑le là où il apporte de la valeur (bases de données, applis stateful) et où vous l’avez testé. Pour certains workloads, les snapshots crash‑consistent sont acceptables et plus simples.

10) What’s the most reliable health check?

qm agent <vmid> ping depuis l’hôte, plus une commande ciblée comme network-get-interfaces. Le ping prouve la connectivité, pas l’utilité.

Conclusion : prochaines étapes réalisables aujourd’hui

Résoudre « l’agent invité n’est pas en cours d’exécution » n’est pas de l’ingénierie héroïque. C’est de l’hygiène basique qui évite des douleurs évitables : arrêts brutaux, visibilité IP manquante, sauvegardes incohérentes. Faites la chose ennuyeuse. Votre futur vous remerciera.

Étapes pratiques :

Choisissez une VM affectée et lancez le triage côté hôte : qm config → qm agent ping → vérifier la socket qga.
Dans le guest, installez et activez l’agent ; vérifiez l’existence du port virtio.
Mettre à jour vos templates et votre provisioning pour que les nouvelles VMs n’aient pas ce problème.
Ajouter un audit hebdomadaire : les VMs avec agent: 0 ou des pings échoués sont corrigées avant les fenêtres de maintenance.

Citation (idée paraphrasée) de Gene Kranz : « Failure isn’t an option » est moins un slogan qu’une ligne de budget opérationnel — payée en vérifications, tests et discipline.

Blague #2 : Si votre seule procédure d’arrêt est « Stop », vous n’avez pas une procédure — vous avez un lancer de pièce avec une interface utilisateur plus jolie.