Dépannage : Machine virtuelle KVM ne démarre plus — analyse systématique des pannes et commandes de réparation

Lorsqu’une KVM‑VM ne démarre soudainement plus, il y a souvent plus en jeu qu’un simple redémarrage. Dans cet article, je présente une analyse d’incident systématique et des commandes de réparation concrètes afin que les administrateurs, ingénieurs système et opérateurs puissent agir de manière sûre et réfléchie. Le mot‑clé principal „KVM-VM ne démarre plus“ est donné dès le début, car les étapes de vérification décrites ici s’appliquent aussi bien aux configurations libvirt/QEMU pures qu’à Proxmox et à d’autres hôtes KVM.

KVM‑VM ne démarre plus : pourquoi une recherche d’erreur structurée est importante

Un échec de démarrage imprévu peut aller d’une simple erreur de configuration à une corruption du stockage. Sans méthode structurée, il y a un risque de perte de données ou de temps d’arrêt inutile. En pratique, il est essentiel d’identifier rapidement, d’utiliser des modes lecture seule sûrs et d’avoir une stratégie de retour en arrière claire.

Aperçu : causes possibles (en un coup d’œil)

• Services hôtes arrêtés (p. ex. libvirtd, qemu‑kvm)
• Problèmes de stockage : LVM‑Thin plein, NFS/ISCSI perdu, Ceph OSD en panne
• Image disque endommagée (qcow2/raw) ou incohérence de snapshot
• Bootloader/EFI/Grub manquant ou initramfs corrompu
• Événements de démarrage réseau/Cloud‑Init bloquant le lancement
• Hardware/kernel panic dans l’invité — pas de console configurée

Préparation : travailler en sécurité et minimiser les risques

Avant d’exécuter des commandes de réparation en écriture, vous devriez créer une sauvegarde ou au moins une copie de l’image disque affectée. De nombreux outils de réparation sont puissants mais non réversibles. Si possible, travaillez sur une copie.

Exemple : créer une copie d’un fichier qcow2 (local) :

cp -v --reflink=auto vmdisk.qcow2 vmdisk.qcow2.bak

Commentaire : reflink=auto utilise, si disponible, CoW sur des systèmes de fichiers tels que XFS ou btrfs ; sinon une copie normale est effectuée. Pour les images volumineuses, cela est souvent plus rapide et plus économe en espace. Si vous travaillez sur un stockage réseau (NFS/SMB), vérifiez au préalable l’espace libre.

Premières vérifications sur l’hôte

Commencez par des contrôles sur l’hôte — de nombreux problèmes proviennent de l’hôte et non de l’invité.

1) État des services de virtualisation

systemctl status libvirtd.service qemu-kvm.service --no-pager

Pourquoi : libvirtd gère les VMs via libvirt ; si le service est arrêté ou si des erreurs apparaissent dans journalctl, les VMs ne démarrent pas. Sur Proxmox le service s’appelle pvedaemon ou pveproxy — vérifiez-les également.

2) Parcourir les logs de l’hôte

journalctl -u libvirtd -n 200
journalctl -k -n 200

Pourquoi : dmesg/journal fournit des indices sur des erreurs de périphérique bloc, des erreurs I/O du noyau ou des pilotes manquants. Si l’hôte rapporte des erreurs I/O, un problème de stockage est probable.

3) Vérifier la couche de stockage

Vérifiez LVM, ZFS, Ceph, NFS ou iSCSI selon la configuration. Exemples :

# LVM Pools
lvs -a -o +lv_name,lv_attr,lv_size,lv_free
# ZFS Pools
zpool status
# Ceph
ceph -s

Pourquoi : un LVM thin peut être plein, les pools ZFS peuvent être dégradés, des OSD peuvent manquer dans Ceph. Si le backend n’est pas disponible, la VM ne démarrera pas ou bloquera lors de l’attachement du disque.

Vérification de la configuration de la VM

Des erreurs dans le XML de la VM (libvirt) ou les chaînes de snapshots QCOW provoquent souvent des erreurs de démarrage.

1) Consulter les infos de domaine et le XML

virsh dominfo vmname
virsh dumpxml vmname > /tmp/vmname.xml

Pourquoi : dumpxml affiche le chemin du disque, le firmware (BIOS vs. OVMF/UEFI), la configuration de la console et les périphériques attachés. Vérifiez les chemins de disque incorrects, les backing stores manquants pour qcow2 ou des indications driver-type erronées.

2) Vérifier les chemins de fichiers des périphériques

ls -lh /var/lib/libvirt/images/vm-100-disk-1.qcow2
qemu-img info /var/lib/libvirt/images/vm-100-disk-1.qcow2

Pourquoi : qemu-img info fournit le format (qcow2/raw), la taille virtuelle et la chaîne de snapshots. Si le backing file manque, qemu ne peut pas démarrer.

Activer la console de l’invité et lire les logs

La console série aide souvent à voir les messages de démarrage dans l’invité. La console série est un accès texte simple pour la sortie du noyau/Grub.

1) Utiliser virsh console

virsh console vmname
# Bei Bedarf: Escape-Sequenz ~. zum Beenden

Pourquoi : si l’invité a une console ttyS0 configurée, vous verrez les messages du noyau et de l’initramfs. Si la console est absente dans l’invité, cette voie ne fonctionne pas — utilisez alors la procédure d’attachement du disque décrite plus bas.

2) Repérer la séquence des hooks de démarrage

Lisez les messages : le blocage survient-il à Grub, à l’initramfs (p. ex. shell busybox) ou plus loin dans le noyau (kernel panic) ? Chaque phase présente des indicateurs propres.

Si l’image disque est suspecte : diagnostic et vérifications sûres

Si la VM bloque lors du montage de la partition root ou si l’initramfs signale des erreurs, vérifiez l’image disque depuis un hôte de secours.

1) Vérifier l’intégrité de l’image

qemu-img check -r all /var/lib/libvirt/images/vm-disk.qcow2

Pourquoi : qemu-img check analyse les structures qcow2. Attention : les réparations doivent être effectuées uniquement après sauvegarde. Si des erreurs sont détectées, créez d’abord une copie de l’image.

2) Monter l’image en lecture seule (guestfish/guestmount)

# Nur lesen, mit libguestfs
guestfish --ro -a /var/lib/libvirt/images/vm-disk.qcow2 -i -- command :
# Alternativ mounten mit libguestfs guestmount
guestmount -a /var/lib/libvirt/images/vm-disk.qcow2 -i /mnt/vmroot --ro

Pourquoi : guestfish / guestmount (libguestfs) permet d’accéder aux partitions à l’intérieur d’une image VM sans manipulation des loop devices au niveau du noyau. Vous pouvez ainsi vérifier /etc/fstab, kernel-cmdline ou les logs cloud-init. Utilisez –ro pour ne pas modifier l’image par erreur.

3) Utiliser loopdev & kpartx (alternative)

losetup -f --show /var/lib/libvirt/images/vm-disk.raw
kpartx -av /dev/loopX
mount /dev/mapper/loopXp1 /mnt/vmroot -o ro

Pourquoi : Si libguestfs n’est pas disponible, vous pouvez convertir l’image (qcow2 → raw) et la monter via un périphérique loop. La conversion prend du temps et de la place ; travaillez sur des copies.

Réparation du système de fichiers ou du chargeur d’amorçage

Si vous pouvez accéder à la partition racine, des réparations sont possibles : fsck, régénération de l’initramfs ou réinstallation de GRUB.

1) Réparer le système de fichiers (toujours sur une copie !)

# Beispiel für ext4 (auf gemounteter oder loopdev ersetztem Device)
e2fsck -f -y /dev/mapper/loopXp1

Pourquoi : e2fsck répare les erreurs du système de fichiers. -f force la vérification, -y répond automatiquement « oui » — n’utilisez -y que si vous comprenez les conséquences. Pour XFS, utilisez xfs_repair ; notez que XFS ne peut typiquement pas être réparé en lecture seule.

2) Régénérer l’initramfs et restaurer GRUB

Si le chargeur d’amorçage ou l’initramfs est endommagé, faites un chroot dans l’image et régénérez :

# Beispielablauf nach Mount der Partitionen
mount --bind /dev /mnt/vmroot/dev
mount --bind /proc /mnt/vmroot/proc
mount --bind /sys /mnt/vmroot/sys
chroot /mnt/vmroot /bin/bash
update-initramfs -u -k all
grub-install --target=i386-pc /dev/sda
update-grub
exit
umount -l /mnt/vmroot/{dev,proc,sys}

Pourquoi : update-initramfs génère l’initramfs nécessaire, qui charge au démarrage les modules et pilotes requis par le noyau. grub-install / update-grub écrit un chargeur d’amorçage fonctionnel. Pour les VM UEFI, faites attention à la configuration OVMF/EFI et utilisez, si nécessaire, grub-install –target=x86_64-efi sur un système EFI.

Risque : chroot et grub-install modifient le contenu du disque. Faites donc une sauvegarde au préalable.

Si le problème vient du firmware (UEFI / OVMF)

De nombreuses VM modernes utilisent OVMF (firmware UEFI pour QEMU). Si les binaires OVMF manquent ou sont mal référencés, la VM ne démarre pas.

# Prüfen ob OVMF vorhanden ist
ls -l /usr/share/OVMF /usr/share/ovmf /usr/share/qemu/OVMF* /usr/share/ovmf/*
# Beispiel: libvirt XML zeigt 

Pourquoi : Des fichiers manquants ou des permissions incorrectes empêchent le chargement du firmware. Vérifiez les mises à jour de paquets ou les changements de fournisseur qui auraient déplacé OVMF.

Si la VM ne démarre pas après une modification du noyau

Les mises à jour du noyau invité ou de l’initramfs peuvent nécessiter un rollback. Si vous disposez de snapshots, examinez la possibilité d’un rollback ; sinon, démarrez dans un environnement de secours et remplacez l’initrd ou la version du noyau.

# In chroot: alte Kernelpakete auflisten und ggf. wieder installieren
apt list --installed | grep Linux-image
apt install Linux-image-
update-grub

Pourquoi : Les mises à jour de paquets peuvent fournir des pilotes/modules incompatibles. Un rollback est souvent la solution la plus rapide, si réalisable rapidement.

Wenn Netzwerk/Cloud‑Init den Boot blockiert

Dans les images basées sur Cloud‑Init, une configuration réseau incorrecte peut retarder ou empêcher le démarrage (p. ex. timeout systemd lors de la demande d’une adresse DHCP). Vérifiez /etc/cloud/cloud.cfg ainsi que les configurations Netplan/ifupdown à l’intérieur de l’image.

# Prüfen von cloud-init Logs (via guestmount/guestfish)
cat /var/log/cloud-init.log
cat /var/log/cloud-init-output.log

Pourquoi : Cloud‑Init peut provoquer des périodes d’attente réseau ; il est souvent utile d’adapter la configuration vers une adresse statique ou des réglages NetworkManager/Netplan plus tolérants.

Relance : rattacher la VM à une Rescue‑VM

Si des réparations de l’image sont nécessaires, attacher le disque à une Rescue‑VM fonctionnelle est la méthode la plus sûre.

# Beispiel libvirt: Disk an Rescue-VM anhängen
virsh attach-disk rescue-vm /var/lib/libvirt/images/vm-disk.qcow2 vdb --driver qemu --subdriver qcow2 --persistent
# Alternative: in Proxmox GUI oder qm set / qm importdisk

Pourquoi : cela permet d’utiliser dans la Rescue‑VM des outils connus pour réparer le système de fichiers ou consulter les logs, sans démarrer la VM cible.

Si tout échoue : RESTaurer un snapshot de disque et appliquer un plan de retour en arrière

Préparez une voie de retour en arrière : snapshots existants, sauvegardes ou réplicas de stockage. Décrivez à l’avance les étapes minimales nécessaires pour rétablir le service (p. ex. démarrer la VM sur un autre hôte, importer le disque depuis un réplica).

Liste de contrôle du retour en arrière

• Localiser une sauvegarde/snapshot valide
• Vérifier l’espace et l’I/O sur l’hôte cible
• Tester l’import/RESTauration du disque sur un hôte séparé
• Effectuer des tests de service (SSH, sanity applicative)
• Communication : indisponibilité, problèmes, fenêtre temporelle du rollback

Pièges typiques et comment les éviter

• Chaînes de snapshots : trop de snapshots qcow2 augmentent la complexité — consolidez avec prudence.
• Thin‑Provisioning : LVM/ZFS thin peut se remplir soudainement — configurez des alertes.
• Versions OVMF incompatibles après mise à niveau de l’hôte — vérifiez les binaires OVMF.
• Absence de console : sans console série, les messages de kernel panic ne sont pas visibles — configurez la console de façon permanente.
• Fautes de frappe dans le XML libvirt (chemin, nom du driver) — vérifiez toujours avec dumpxml.

Exemple pratique : image qcow2 – backing file manquant

Symptôme : la VM ne démarre pas, qemu signale ‚missing backing file‘.

# Diagnose
qemu-img info vm-disk.qcow2
# Ausgabe zeigt backing file: /var/lib/libvirt/images/base.qcow2 (missing)
# Lösung: ersetzen oder rekreieren backing file
cp /backup/base.qcow2 /var/lib/libvirt/images/
chown libvirt-qemu:kvm /var/lib/libvirt/images/base.qcow2
# Alternativ: rebase um den Backing-Referenzpfad zu entfernen (auf Kopie!)
qemu-img rebase -u -b "" vm-disk.qcow2

Pourquoi : qcow2 peut fonctionner avec un backing file ; si celui‑ci est manquant, l’image est incohérente. qemu-img rebase supprime la liaison au backing file, cela ne fonctionne que si les données sont autonomes et correctes — donc effectuer un backup au préalable.

Indications de monitoring et de prévention

Pour éviter de futurs incidents, mettez en place les éléments suivants :

• Alertes pour le remplissage du stockage (LVM/ZFS/Thin/Datastore)
• Scrubs/contrôles réguliers (p. ex. ZFS scrub, Ceph health checks)
• RESTaurations de test automatisées pendant les fenêtres de maintenance
• Console série comme standard dans les templates de VM
• Runbooks de récupération documentés pour les VMs critiques

Conclusion et liste de priorités pour l’analyse des incidents

Si une KVM‑VM ne démarre plus, procédez de façon structurée : services de l’hôte, stockage, configuration de la VM, console et intégrité des disques. Travaillez toujours sur des copies, documentez chaque étape et prévoyez une option de retour en arrière. Dans la plupart des cas, l’incident peut être résolu par une combinaison d’analyse en lecture seule (guestmount/guestfish), de réparation du système de fichiers et, si nécessaire, de régénération de l’initramfs/GRUB.

Si vous souhaitez une liste de vérification rapide, commencez par les étapes suivantes :

1. Vérifier les logs et services de l’hôte (libvirtd/qemu, dmesg)
2. Contrôler le back-end de stockage (LVM/ZFS/Ceph/NFS)
3. Vérifier le XML de la VM et le chemin des disques
4. Activer la console série et consulter les logs
5. Monter l’image en lecture seule de manière sûre et vérifier son contenu
6. Sur une copie : fsck, régénération de l’initramfs et réinstallation de GRUB

Ce billet a pour objectif de servir d’introduction pratique au runbook : techniquement précis, avec des commandes concrètes et toujours axé sur la sécurité d’exploitation et les stratégies de récupération.