Votre VM Debian démarre, son réseau fonctionne, mais Proxmox affiche encore « Guest Agent not running » ou ne remonte aucune information. L’option QEMU Guest Agent cochée dans l’interface ne suffit pas à établir l’échange avec l’invité.
QEMU Guest Agent installe un démon dans Debian et crée un canal de gestion entre la VM et l’hôte. Vous allez vérifier les deux côtés, puis isoler une panne de configuration, de service ou de périphérique sans modifier le réseau de la VM.
À quoi sert QEMU Guest Agent dans Proxmox ?
Une VM peut fonctionner normalement sans agent. Proxmox voit alors la machine virtuelle, mais il ne dispose pas du même niveau d’informations sur le système Debian qui tourne à l’intérieur.
QEMU Guest Agent exécute qemu-ga dans l’invité. Le démon échange avec l’hyperviseur par un périphérique virtio-serial, généralement exposé dans Debian sous /dev/virtio-ports/org.qemu.guest_agent.0. Proxmox peut ainsi demander des informations à la VM, organiser un arrêt propre et coordonner le gel puis le dégel du système de fichiers pendant certaines sauvegardes ou certains snapshots.
La documentation officielle de Proxmox et celle de QEMU décrivent cette chaîne hôte, canal virtuel et démon invité. L’agent ne remplace ni le pilote réseau VirtIO, ni DHCP, ni le bridge, ni le pare-feu.
Activer l’agent côté Proxmox avant de toucher Debian
Commencez par arrêter la VM si vous prévoyez de modifier sa configuration matérielle. Dans l’interface Proxmox, ouvrez la VM Debian, allez dans Options, éditez QEMU Guest Agent, puis activez l’option. Vérifiez aussi le VMID affiché dans l’interface : il servira uniquement sur l’hôte Proxmox.
Je vous conseille de vérifier cette option côté Proxmox avant d’installer le paquet dans Debian. Vous séparerez ainsi une absence de canal virtuel d’un simple service manquant.
L’équivalent en ligne de commande indiqué par Proxmox est le suivant :
qm set VMID --agent 1Remplacez VMID par l’identifiant numérique de votre VM. Cette action active l’option côté hôte. Elle ne démarre pas le service Debian et ne prouve pas la présence du canal virtio-serial.
Si le réglage vient d’être ajouté et que le périphérique n’apparaît pas dans l’invité, faites un arrêt puis un démarrage contrôlé de la VM. Ne partez pas du principe qu’un branchement à chaud sera disponible dans toutes les configurations.
Installer et démarrer qemu-guest-agent dans Debian
Ouvrez un terminal dans la VM Debian. Une mise à jour de l’index APT évite de travailler avec des métadonnées périmées :
sudo apt-get update
sudo apt-get install qemu-guest-agentContrôlez ensuite l’unité systemd au lieu d’enchaîner immédiatement les redémarrages :
sudo systemctl status qemu-guest-agent --no-pagerVous devez obtenir un service connu et un état active (running). S’il est installé mais inactif, démarrez-le puis activez son lancement avec Debian :
sudo systemctl start qemu-guest-agent
sudo systemctl enable qemu-guest-agentRelisez systemctl status après ces actions. Un message d’erreur reste plus utile qu’une nouvelle tentative identique. L’installation du paquet ne touche pas la carte réseau, le bridge ou la configuration IP.
Vérifier le canal virtio-serial dans la VM
Un service actif peut attendre un périphérique que la VM ne présente pas. Vérifiez le chemin utilisé par QEMU Guest Agent :
ls -l /dev/virtio-ports/org.qemu.guest_agent.0Le fichier doit être présent. S’il manque, la réinstallation du paquet ne réglera rien. Relisez d’abord l’option QEMU Guest Agent dans Proxmox, puis la configuration matérielle de la VM. Un arrêt et un démarrage contrôlés peuvent être nécessaires après la modification.
Si le chemin existe mais que Proxmox ne reçoit toujours aucune réponse, lisez les derniers messages du service :
sudo journalctl -u qemu-guest-agent --no-pager -n 50La manpage officielle Debian de qemu-ga documente aussi /etc/qemu/qemu-ga.conf et le transport virtio-serial. Gardez cette piste pour une erreur clairement liée au démon ou à son canal, pas pour une panne d’adresse IP.
Tester la réponse depuis l’hôte Proxmox
Attention : le statut active (running) dans Debian confirme le service, pas la réponse reçue par l’hôte. Pour vérifier la syntaxe disponible sur votre version de Proxmox, commencez sur l’hôte par ce préflight :
qm help agentCette aide doit confirmer la forme exacte attendue par votre installation. Exécutez ensuite uniquement la forme qm agent affichée par ce préflight, avec le VMID concerné. Je ne donne pas de sous-commande supposée ici : elle peut varier selon la version de l’outil, et une commande inventée ne constitue pas un test.
Le résultat attendu est une réponse d’information cohérente avec la VM affichée dans Proxmox. Comparez-la avec l’état de l’agent dans l’interface. Une adresse IP visible peut aider, mais elle ne suffit pas à prouver le fonctionnement complet du canal de gestion.
Corriger la panne dans la bonne couche
Quand plusieurs symptômes se ressemblent, ce tableau évite de réinstaller Debian alors que le périphérique manque côté VM.
| Symptôme | Couche probable | Commande ou contrôle | Action minimale |
|---|---|---|---|
| Option inactive | Proxmox | Options de la VM | Activer QEMU Guest Agent, puis redémarrer la VM si le canal n’apparaît pas. |
| Unité inconnue | Debian | systemctl status qemu-guest-agent | Installer le paquet avec APT, puis relire l’état du service. |
| Service en erreur | Debian | systemctl status et journalctl | Lire la première erreur avant tout nouveau démarrage. |
| Périphérique absent | virtio-serial | ls -l /dev/virtio-ports/org.qemu.guest_agent.0 | Corriger l’option ou le matériel virtuel côté Proxmox, puis effectuer un cycle d’arrêt et de démarrage. |
Si l’agent répond depuis l’hôte mais que la VM n’a toujours pas de réseau, arrêtez le diagnostic QEMU Guest Agent à cet endroit. La connectivité relève du bridge, de l’interface virtuelle ou de Debian. Le post Rétablir le réseau d’une VM Proxmox, du bridge à l’invité couvre cette chaîne sans mélanger les deux problèmes.
Si le contrôle montre un défaut du bridge sur l’hôte, utilisez plutôt Créer un bridge Proxmox sans perdre l’accès au serveur. Ne modifiez pas le bridge pour corriger un agent non détecté : les deux couches communiquent, mais elles ne remplissent pas le même rôle.
Valider l’arrêt et les sauvegardes sans surpromettre
Une réponse valide depuis l’hôte permet ensuite de contrôler les bénéfices attendus. Effectuez un arrêt invité contrôlé depuis Proxmox, puis consultez la tâche et les journaux de l’hôte. La VM doit s’arrêter proprement au lieu de subir une coupure forcée.
Pour une sauvegarde ou un snapshot qui utilise le gel du système de fichiers, vérifiez aussi les messages de tâche. Le gel et le dégel améliorent la cohérence du système de fichiers. Ils ne garantissent pas la cohérence applicative de toutes les bases de données : une base doit encore suivre sa propre procédure de sauvegarde.
Voici les quatre preuves à réunir avant de considérer l’installation terminée :
- l’option QEMU Guest Agent est active côté Proxmox ;
- le paquet et le service sont présents dans Debian ;
- le périphérique virtio-serial existe sous le chemin attendu ;
- l’hôte reçoit une réponse après le préflight
qm help agentet le test adapté à sa version.
Le canal est validé quand ces quatre contrôles concordent. S’il répond, laissez le réseau tranquille : il ne manque pas d’agent pour réparer un bridge.