Proxmox : installer le qemu-guest-agent dans une VM cloud-init

Vous avez créé une VM depuis une cloud-image (Debian, Ubuntu), coché l'option QEMU Guest Agent, et pourtant Proxmox affiche « Guest Agent not running » et aucune IP dans l'onglet Summary. C'est le grand classique : les cloud-images n'embarquent pas l'agent, et l'option côté VM ne suffit pas. Ce guide explique les trois pièces du puzzle et les trois méthodes pour installer l'agent, avec la plus fiable (cloud-init) testée sur PVE 9. Pour qui automatise des VMs cloud-init.

Ce que vous allez apprendre

• Pourquoi « Guest Agent not running » malgré l'option cochée.
• Installer l'agent proprement via cloud-init (snippet).
• Les alternatives (virt-customize, post-boot) et leurs pièges.
• Vérifier que l'agent répond et que l'IP remonte.

À quoi sert l'agent

Le qemu-guest-agent est un petit démon dans l'invité qui donne à Proxmox trois services :

• Remonter l'IP dans l'onglet Summary (sans lui, le réseau marche, mais l'IP ne s'affiche pas côté hyperviseur) ;
• arrêt propre de la VM (qm shutdown passe par l'agent au lieu d'un ACPI brutal) ;
• sauvegardes cohérentes : Proxmox gèle le système de fichiers (fsfreeze) le temps du snapshot.

Le vrai problème : trois pièces, pas une

L'erreur la plus fréquente est de croire qu'une action suffit. Il en faut trois, réparties des deux côtés.

Étape	Où	Commande	Si oubliée
Activer le canal	côté VM	qm set <vmid> --agent enabled=1	l'agent ne peut pas communiquer
Installer le paquet	côté invité	apt install qemu-guest-agent	le canal n'écoute rien
Activer le service	côté invité	systemctl enable --now qemu-guest-agent	l'agent est là mais inactif

Glissez pour voir

Les cloud-images n'ont pas le paquet : c'est l'étape 2 (et 3) qui manque presque toujours.

Méthode 1 : cloud-init (la plus fiable)

Pour une VM cloud-init, on demande à cloud-init d'installer et d'activer l'agent au premier boot, via un snippet. Le stockage doit accepter le contenu snippets (sur local, dans /var/lib/vz/snippets/).

1. Créer le snippet /var/lib/vz/snippets/qemu-agent.yaml :

   #cloud-config
   packages:
     - qemu-guest-agent
   runcmd:
     - systemctl enable --now qemu-guest-agent

2. Attacher le snippet à la VM avec vendor= (surtout pas user=) :

   qm set <vmid> --cicustom "vendor=local:snippets/qemu-agent.yaml"

vendor, pas user

Proxmox génère déjà la config user de cloud-init (utilisateur, clés SSH, mot de passe de l'onglet Cloud-Init). L'écraser avec user= détruirait ces réglages. Le vendor= s'ajoute sans rien casser. On inspecte ce que Proxmox génère avec qm cloudinit dump <vmid> vendor.

Sur le lab, la preuve que cela fonctionne, une fois la VM démarrée :

qm agent <vmid> ping
# (aucune erreur = l'agent répond)
qm agent <vmid> network-get-interfaces
# ... "ip-address": "192.168.10.238" ...  -> l'IP remonte

cloud-init n'installe rien sans réseau au 1er boot

Le packages: de cloud-init n'installe le paquet que si le réseau est disponible au premier démarrage. Si le réseau manque à ce moment, l'apt install échoue en silence et aucune nouvelle tentative n'a lieu ensuite. Pour des VMs sans réseau au boot, préférez baker le paquet dans le template.

Méthode 2 : virt-customize (attention au piège)

On peut aussi injecter l'agent dans l'image avant de créer la VM :

apt install -y libguestfs-tools
virt-customize -a debian-13-genericcloud-amd64.qcow2 \
  --install qemu-guest-agent \
  --run-command 'systemctl enable qemu-guest-agent' \
  --truncate /etc/machine-id

virt-customize qui « réussit » sans rien installer

Piège vécu et reproductible : virt-customize affiche « Finishing off » comme si tout allait bien, mais le paquet est absent (qemu-guest-agent.service could not be found). Cause : l'appliance libguestfs n'a pas de DNS, donc l'apt install échoue silencieusement. Correctif sur PVE 9 : installer dhcpcd-base sur l'hôte avant de lancer virt-customize (sans lui, l'appliance ne configure pas son réseau). Puis vérifiez que le paquet est bien là, ne vous fiez pas au « Finishing off ».

Le --truncate /etc/machine-id évite que tous les clones héritent du même machine-id (et donc de la même IP DHCP).

Méthode 3 : dans la VM déjà démarrée

Le plus direct quand la VM tourne déjà et qu'on peut s'y connecter :

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

Activer le canal et redémarrer à froid

Quelle que soit la méthode, il faut activer le canal côté Proxmox et redémarrer à froid.

qm set <vmid> --agent enabled=1
qm stop <vmid> && qm start <vmid>

Un reboot soft ne suffit PAS

L'option --agent enabled=1 ajoute un port virtio-serial, du matériel virtuel. Il n'apparaît qu'au prochain démarrage complet du process QEMU. Un reboot depuis l'OS invité ne le crée pas : il faut un vrai stop puis start. C'est l'erreur n°1. Le device attendu dans l'invité est /dev/virtio-ports/org.qemu.guest_agent.0 ; s'il est absent, le cold reboot n'a pas eu lieu.

Vérifier de bout en bout

# depuis l'hôte Proxmox
qm agent <vmid> ping                    # pas d'erreur = communication OK
qm agent <vmid> network-get-interfaces  # l'IP doit apparaître

# dans l'invité
ls -l /dev/virtio-ports/org.qemu.guest_agent.0   # le device existe
systemctl is-active qemu-guest-agent             # active

La preuve complète : qm agent ping ne renvoie aucune erreur et l'IP apparaît dans l'onglet Summary de l'interface.

Pièges courants

Symptôme	Cause	Solution
« Guest Agent not running » persistant	option cochée mais paquet absent	installer qemu-guest-agent dans l'invité
Toujours rien après install	pas de cold reboot	qm stop puis qm start
virt-customize « réussit » mais agent absent	pas de DNS dans l'appliance	dhcpcd-base sur l'hôte PVE 9
systemctl ne trouve rien	on cherche qemu-ga	l'unité est qemu-guest-agent, le process qemu-ga
Clones avec la même IP	machine-id identique	--truncate /etc/machine-id à l'image

Glissez pour voir

À retenir

• Trois pièces : activer le canal (--agent enabled=1), installer le paquet, activer le service. L'option seule ne suffit pas.
• Pour une cloud-image, la méthode fiable est cloud-init avec un snippet vendor= (packages: qemu-guest-agent).
• virt-customize échoue silencieusement sans DNS : installez dhcpcd-base sur l'hôte PVE 9 et vérifiez.
• Après --agent enabled=1, faites un cold reboot (stop/start), pas un reboot interne.
• Preuve : qm agent ping sans erreur et l'IP dans l'onglet Summary.

FAQ : questions fréquentes sur le qemu-guest-agent Proxmox

Pourquoi Proxmox affiche « Guest Agent not running » malgré l'option cochée ?

Parce que cocher l'option QEMU Guest Agent active seulement le canal côté VM, mais n'installe pas le paquet dans l'invité. Les cloud-images n'embarquent pas qemu-guest-agent. Il faut les trois pièces : activer le canal, installer le paquet dans l'invité, et activer le service.

Comment installer qemu-guest-agent dans une VM cloud-init Proxmox ?

La méthode fiable est un snippet cloud-init. On crée un fichier dans /var/lib/vz/snippets contenant packages: qemu-guest-agent et un runcmd systemctl enable, puis on l'attache avec qm set vmid --cicustom vendor=local:snippets/fichier.yaml.

Faut-il redémarrer la VM après avoir activé l'agent Proxmox ?

Oui, et il faut un redémarrage à froid (qm stop puis qm start), pas un reboot depuis l'OS. L'option --agent enabled=1 ajoute un port virtio-serial, du matériel virtuel, qui n'apparaît qu'au prochain démarrage complet du process QEMU. Un reboot interne à l'invité ne recrée pas ce device.

Pourquoi virt-customize n'installe pas le qemu-guest-agent ?

Parce que l'appliance libguestfs utilisée par virt-customize n'a pas de résolution DNS, donc l'apt install échoue en silence tout en affichant Finishing off.

Comment vérifier que le qemu-guest-agent fonctionne sur Proxmox ?

Depuis l'hôte, qm agent vmid ping ne doit renvoyer aucune erreur, et qm agent vmid network-get-interfaces doit afficher l'IP de la VM. Dans l'invité, le device /dev/virtio-ports/org.qemu.guest_agent.0 doit exister et systemctl is-active qemu-guest-agent doit renvoyer active.

Prochaines étapes

Créer une VM Proxmox Les bons réglages de VM dès le départ.

Provisionner avec Terraform Des VMs cloud-init automatisées.

Proxmox VE, qu'est-ce que c'est ? Les fondamentaux de la plateforme.

×

📖 Voir la documentation →