QEMU Guest Agent : quand l'hyperviseur doit parler à l'invité

Un hyperviseur ne voit pas ce qui se passe à l'intérieur de ses machines. Il connaît le disque virtuel, pas les systèmes de fichiers ; la carte réseau, pas les adresses configurées. Le QEMU Guest Agent est le petit service qui comble cet écart : installé dans la VM, il répond aux questions de l'hôte. Sans lui, virsh domfsinfo, virsh guestinfo et surtout snapshot --quiesce échouent, et vos sauvegardes ne valent pas ce que vous croyez.

Ce que vous allez apprendre

• Distinguer le canal, posé par l'hôte, de l'agent, installé dans la VM
• Lire les deux messages d'erreur de libvirt, qui ne disent pas la même chose
• Installer l'agent et vérifier qu'il répond vraiment
• Obtenir les IP réelles, les systèmes de fichiers et l'identité de l'invité
• Comprendre ce que l'agent expose, et ce que cela implique

Prérequis

Ce guide suppose une VM déjà démarrée et l'accès à l'hôte avec virsh. Les sorties présentées viennent d'une machine Ubuntu 24.04 créée par virt-install sur libvirt 10, mais le mécanisme est identique sur toutes les distributions : seul le nom du paquet change.

• KVM/libvirt installé (guide installation)
• Une VM en cours d'exécution (créer une VM)
• Un accès à l'intérieur de la VM, par SSH ou par console

Le canal et l'agent : deux moitiés d'un même pont

C'est la confusion qui fait perdre le plus de temps sur ce sujet. Il faut deux pièces pour que l'hôte parle à l'invité, et elles s'installent à deux endroits différents :

Pièce	Où elle vit	Qui la pose
Le canal org.qemu.guest_agent.0	dans le XML du domaine, côté hôte	libvirt, souvent automatiquement
Le paquet qemu-guest-agent	dans le système invité	vous, comme n'importe quel paquet

Glissez pour voir

Vérifiez d'abord la présence du canal, côté hôte :

virsh dumpxml ma-vm | grep -A3 org.qemu.guest_agent

La sortie contient un attribut qui dit tout, et que l'on oublie de lire :

<target type='virtio' name='org.qemu.guest_agent.0' state='disconnected'/>

state='disconnected' signifie que le pont est construit d'un seul côté. Le canal existe, mais personne ne répond au bout. C'est l'état normal d'une VM fraîchement créée, tant que le paquet n'est pas installé dans l'invité.

Le canal dépend de l'os-variant déclaré

virt-install pose le canal tout seul quand vous lui donnez un --osinfo reconnu, par exemple ubuntu24.04. Avec un --osinfo generic, il ne le pose pas, et aucune option d'agent ne fonctionnera ensuite. C'est une raison de plus de renseigner correctement la variante du système à la création.

Pour ajouter le canal à une VM existante, virsh edit ma-vm puis, dans <devices> :

<channel type='unix'>
  <target type='virtio' name='org.qemu.guest_agent.0'/>
</channel>

Contrairement à l'installation du paquet, cet ajout demande un arrêt puis un redémarrage complet de la machine, pas un simple reboot depuis l'invité.

Les deux erreurs de libvirt, et ce qu'elles vous disent

Quand une commande qui a besoin de l'agent échoue, libvirt renvoie l'un de deux messages distincts. Les confondre envoie chercher au mauvais endroit :

Message	Ce qui manque	Où corriger
QEMU guest agent is not configured	le canal, absent du XML	sur l'hôte, virsh edit puis arrêt et redémarrage
QEMU guest agent is not responding: ... is not connected	le paquet, absent de l'invité	dans la VM, installer qemu-guest-agent

Glissez pour voir

Le second est de loin le plus fréquent. Voici ce que donne une VM dont le canal existe mais dont l'invité n'a pas l'agent, commande par commande :

$ virsh domifaddr ma-vm --source agent
error: Guest agent is not responding: QEMU guest agent is not connected

$ virsh domfsinfo ma-vm
error: Unable to get filesystem information
error: Guest agent is not responding: QEMU guest agent is not connected

$ virsh snapshot-create-as ma-vm --name snap --disk-only --quiesce
error: Guest agent is not responding: QEMU guest agent is not connected

Ces échecs sont une bonne nouvelle. libvirt refuse plutôt que de vous rendre un résultat dégradé : un --quiesce qui échouerait en silence vous laisserait croire à une sauvegarde cohérente qui n'en est pas une.

Installer l'agent

L'installation se fait dans la machine invitée, pas sur l'hôte. Le paquet porte le même nom sur toutes les grandes familles, et le service démarre seul.

1. Installer le paquet dans la VM

   sudo apt install -y qemu-guest-agent      # Debian, Ubuntu
   sudo dnf install -y qemu-guest-agent      # RHEL, Rocky, Alma, Fedora

2. Vérifier que le service tourne

   systemctl is-active qemu-guest-agent

   La réponse attendue est active. Sur la plupart des images cloud, le service démarre immédiatement, sans action supplémentaire.

3. Revenir sur l'hôte et constater la bascule

   virsh dumpxml ma-vm | grep -oE "state='(dis)?connected'"

   L'attribut est passé à state='connected', et cela sans redémarrer la machine : le canal était déjà là, il vient simplement de trouver son interlocuteur.

4. Confirmer par un aller-retour

   virsh qemu-agent-command ma-vm '{"execute":"guest-ping"}'

   La réponse {"return":{}} est laconique mais sans ambiguïté : l'agent a reçu la demande et a répondu.

Ce que l'agent débloque

Les quatre commandes ci-dessous échouaient toutes une minute plus tôt. C'est le meilleur moyen de comprendre ce que l'agent apporte réellement.

Les adresses vues de l'intérieur

virsh domifaddr ma-vm --source agent

 Name       MAC address          Protocol     Address
-------------------------------------------------------------------------------
 lo         00:00:00:00:00:00    ipv4         127.0.0.1/8
 enp1s0     52:54:00:79:88:c6    ipv4         192.168.122.39/24
 -          -                    ipv6         fe80::5054:ff:fe79:88c6/64

Comparez avec la source par défaut, qui lit les baux DHCP de libvirt : elle ne connaît que vnet33, le nom de l'interface côté hôte, une seule adresse IPv4, et rien du tout si la VM utilise une adresse statique ou un réseau en bridge. L'agent, lui, donne le nom réel de l'interface dans le système, enp1s0, et les adresses IPv6.

Les systèmes de fichiers montés

virsh domfsinfo ma-vm

 Mountpoint   Name    Type   Target
-------------------------------------
 /            vda1    ext4   vda
 /boot        vda16   ext4   vda
 /boot/efi    vda15   vfat   vda

L'hôte voit un disque virtuel ; l'agent lui apprend son découpage et le type de chaque système de fichiers. C'est ce qui permet de savoir quoi geler au moment d'une sauvegarde, et de repérer un /boot saturé sans ouvrir de session.

L'identité de l'invité

virsh guestinfo ma-vm

os.pretty-name      : Ubuntu 24.04.5 LTS
os.kernel-release   : 6.8.0-139-generic
timezone.name       : UTC
hostname            : kvmdoc-agent

Sur un parc de machines, c'est un inventaire obtenu sans se connecter nulle part : version exacte du système, noyau en cours, nom d'hôte réel, fuseau horaire. La commande virsh domtime complète le tableau en donnant l'horloge de l'invité, utile pour repérer une dérive après une suspension.

Le gel des systèmes de fichiers

C'est la fonction la plus importante, et celle dont dépend toute sauvegarde sérieuse. L'agent sait demander au noyau invité de suspendre les écritures le temps de prendre une image :

virsh domfsfreeze ma-vm     # Froze 2 filesystem(s)
virsh domfsthaw ma-vm       # Thawed 2 filesystem(s)

Vous n'aurez presque jamais à les taper : c'est exactement ce que fait --quiesce en interne, en encadrant la prise du snapshot.

virsh snapshot-create-as ma-vm --name avant-maj --disk-only --quiesce

Geler n'est pas rendre une base de données cohérente

--quiesce amène le snapshot au niveau filesystem-consistent : aucun journal à rejouer au redémarrage. Il ne dit rien de ce qu'une base de données garde dans ses tampons ou dans une transaction ouverte. Pour un PostgreSQL ou un MySQL, il faut en plus un hook applicatif, ou la sauvegarde native du moteur. Les trois niveaux de cohérence sont détaillés dans Snapshots, clones et backups.

L'arrêt propre

virsh shutdown demande par défaut un arrêt par ACPI, l'équivalent d'un appui sur le bouton d'alimentation : le système invité est libre de l'ignorer. Avec l'agent, l'ordre passe par un canal que l'invité traite comme une demande d'arrêt véritable :

virsh shutdown ma-vm --mode agent

Sur un serveur sans interface graphique, où aucun gestionnaire de session n'écoute les événements ACPI, c'est souvent la différence entre une machine qui s'arrête et une machine qui reste allumée jusqu'au destroy.

Ce que l'agent expose, et ce qu'il faut en penser

Installer l'agent donne à l'hôte des moyens d'action à l'intérieur de l'invité : lire des informations, geler des systèmes de fichiers, et selon la configuration, exécuter des commandes ou lire des fichiers. Ce n'est pas un problème dans le cas normal, où l'administrateur de l'hyperviseur est déjà celui des machines : qui contrôle l'hôte peut de toute façon lire les disques.

Cela le devient dans un contexte d'hébergement multi-locataire, où le propriétaire de la VM n'est pas celui de l'hôte. libvirt permet alors de désactiver les commandes sensibles de l'agent, par la ligne BLACKLIST_RPC du fichier /etc/sysconfig/qemu-ga sur les distributions RHEL, ou son équivalent /etc/default/qemu-guest-agent, en passant l'option --block-rpcs au service. Les fonctions d'inventaire et de gel restent disponibles, celles qui exécutent du code ne le sont plus.

Dépannage

Symptôme	Cause probable	Vérification
is not configured	canal absent du XML	virsh dumpxml ma-vm | grep guest_agent
is not connected	paquet absent dans l'invité	systemctl is-active qemu-guest-agent dans la VM
state='disconnected' persistant	service arrêté ou VM jamais redémarrée après ajout du canal	systemctl status qemu-guest-agent
domifaddr vide sans --source agent	IP statique ou réseau bridge	relancer avec --source agent
L'agent répond, --quiesce échoue	système de fichiers non gelable	virsh domfsinfo pour voir les types montés

Glissez pour voir

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• Il faut deux pièces : le canal dans le XML côté hôte, le paquet dans l'invité. L'une sans l'autre ne sert à rien.
• L'attribut state='connected' du canal est la preuve que les deux moitiés se sont trouvées, et il bascule sans redémarrer la machine.
• Les deux messages d'erreur ne désignent pas le même manque : not configured vise l'hôte, not connected vise l'invité.
• L'agent donne les adresses réelles, y compris IPv6 et sur réseau bridge, là où la source DHCP ne voit que ses propres baux.
• Sans agent, --quiesce échoue au lieu de produire une sauvegarde qui semblerait bonne. C'est le comportement souhaitable.
• virsh shutdown --mode agent arrête une machine que l'ACPI seul laisserait allumée.

Pour aller plus loin

• Snapshots, clones et backups : Ce que --quiesce garantit vraiment, et l'API de sauvegarde live de libvirt.
• Accès distant à libvirt : Piloter l'hyperviseur, et donc l'agent, depuis votre poste.
• Dépannage réseau KVM : Quand domifaddr reste vide alors que la VM répond.

×

📖 Voir la documentation →