Risoluzione dei problemi: la VM KVM non si avvia più — analisi sistematica dei guasti e comandi di riparazione

Quando una KVM‑VM improvvisamente non si avvia più, spesso è in gioco più di un semplice riavvio. In questo articolo mostro una analisi sistematica degli errori e comandi di riparazione concreti, in modo che amministratori, ingegneri di sistema e operatori possano procedere in modo sicuro e consapevole dei rischi. La parola chiave principale „KVM-VM non si avvia più“ viene citata subito, perché i passaggi di verifica descritti qui si applicano sia a setup puri libvirt/QEMU sia a Proxmox e ad altri host KVM.

KVM-VM non si avvia più: perché una ricerca guasti strutturata è importante

Un fallimento di avvio non pianificato può andare da un semplice errore di configurazione fino a una corruzione dello storage. Senza un approccio strutturato si rischiano perdite di dati o tempi di inattività evitabili. In pratica servono identificazione rapida, modalità di accesso in sola lettura sicure e una chiara strategia di rollback.

Panoramica: possibili cause (a colpo d’occhio)

• Servizi host interrotti (ad es. libvirtd, qemu‑kvm)
• Problemi di storage: LVM‑Thin pieno, NFS/ISCSI non raggiungibile, Ceph OSD down
• Immagine disco danneggiata (qcow2/raw) o inconsistenza di snapshot
• Bootloader/EFI/Grub assente o initramfs corrotto
• Eventi di boot di rete/Cloud‑Init che bloccano l’avvio
• Panico hardware/kernel nel guest — nessuna console configurata

Preparazione: lavorare in sicurezza e minimizzare i rischi

Prima di eseguire comandi di riparazione con operazioni in scrittura, create un backup o almeno una copia dell’immagine disco interessata. Molti strumenti di riparazione sono potenti ma non reversibili. Se possibile, lavorate su una copia.

Esempio: creare una copia di un file qcow2 (locale):

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

Commento: reflink=auto usa, se disponibile, CoW su filesystem come XFS o btrfs; altrimenti viene creata una copia normale. Con immagini grandi questo è spesso più veloce e occupa meno spazio. Se lavorate su network‑storage (NFS/SMB), verificate prima lo spazio libero.

Primi controlli sull’Host

Iniziate con controlli sull’host — molti problemi non sono causati dal guest ma dall’host.

1) Stato dei servizi di virtualizzazione

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

Perché: libvirtd gestisce le VM via libvirt; se il servizio è fermo o appaiono errori in journalctl, le VM non si avviano. Su Proxmox il servizio si chiama pvedaemon o pveproxy — verificate anche questi.

2) Cercare nei log dell’Host

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

Perché: dmesg/journal fornisce indicazioni su errori di block‑device, Kernel‑I/O‑Errors o driver mancanti. Se l’host segnala I/O‑Errors, probabilmente c’è un problema di storage.

3) Verificare il layer di storage

Controllate LVM, ZFS, Ceph, NFS o iSCSI a seconda della configurazione. Esempi:

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

Perché: LVM‑Thin può riempirsi, i pool ZFS possono essere degradati, in Ceph possono mancare OSD. Se il backend non è disponibile, la VM non si avvierà o rimarrà bloccata durante l’attach del disco.

Verifica della configurazione della VM

Errori nella VM‑XML (libvirt) o nelle catene di snapshot QCOW frequentemente causano errori di boot.

1) Visualizzare le informazioni della domain e l’XML

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

Perché: dumpxml mostra il percorso del disco, la firmware (BIOS vs. OVMF/UEFI), la configurazione della console e i dispositivi collegati. Prestate attenzione a percorsi disco errati, backing stores mancanti per qcow2 o a impostazioni driver‑type errate.

2) Verificare i percorsi dei file dei device

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

Perché: qemu-img info fornisce il formato (qcow2/raw), la virtual size e la catena di snapshot. Se il backing file manca, qemu non può avviarsi.

Attivare la console del guest e leggere i log

Spesso la console seriale aiuta a vedere i messaggi di boot nel guest. La console seriale è un accesso testuale all’output del kernel/Grub.

1) Usare virsh console

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

Perché: se nel guest è configurata una console ttyS0, vedrete i messaggi del kernel e dell’initramfs. Se la console manca nel guest, questa via non funziona — in tal caso usate la procedura di attach del disco più avanti.

2) Riconoscere l’ordine dei Boot‑Hooks

Leggete i messaggi: si blocca in Grub, nell’initramfs (ad es. busybox Shell) o più avanti nel kernel (Kernel panic)? Ogni fase ha indicatori propri.

Se l’immagine del disco è sospetta: diagnostica e controlli sicuri

Se la VM si blocca durante il mount della partizione root o l’initramfs segnala errori, verificate l’immagine del disco su un rescue‑host.

1) Controllare l’integrità dell’immagine

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

Perché: qemu-img check analizza le strutture qcow2. Attenzione: le riparazioni devono essere eseguite solo dopo un backup. Se vengono trovati errori, create prima una copia dell’immagine.

2) Montare l’immagine in sola lettura (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

Perché: guestfish / guestmount (libguestfs) consente l’accesso alle partizioni all’interno di un’immagine VM senza manipolare il loop device del kernel. In questo modo è possibile verificare /etc/fstab, kernel‑cmdline o i log di cloud‑init. Usare –ro per evitare di modificare accidentalmente l’immagine.

3) Loopdev & kpartx verwenden (Alternative)

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

Perché: se libguestfs non è disponibile, è possibile convertire l’immagine (qcow2 → raw) e montarla tramite loop device. La conversione richiede tempo e spazio; lavorare su copie.

Riparazione del filesystem o del bootloader

Se è possibile accedere alla partizione root, sono possibili riparazioni: fsck, rigenerazione dell’initramfs o reinstallazione di GRUB.

1) Filesystem reparieren (immer auf Kopie!)

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

Perché: e2fsck ripara gli errori del filesystem. -f forza il controllo, -y risponde automaticamente Sì — usare -y solo se si comprendono le conseguenze. Per XFS usare xfs_repair; tenere presente che XFS di norma non può essere riparato in modalità read‑only.

2) Initramfs neu erstellen und GRUB wiederherstellen

Se il bootloader o l’initramfs sono danneggiati, eseguire un chroot nell’immagine e rigenerare:

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

Perché: update-initramfs genera l’initramfs necessario, che al boot del kernel carica moduli e driver a runtime. grub-install/ update-grub scrivono un bootloader funzionante. Per VM UEFI verificare la configurazione OVMF/EFI e, se necessario, usare grub-install –target=x86_64-efi su un sistema EFI.

Rischio: chroot e grub-install modificano il contenuto del disco. Perciò creare un backup prima.

Se il problema dipende dal firmware (UEFI / OVMF)

Molte VM moderne utilizzano OVMF (firmware UEFI per QEMU). Se i file binari OVMF mancano o sono referenziati in modo errato, la VM non si avvia.

# 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 

Perché: file mancanti o permessi errati impediscono il caricamento del firmware. Verificare aggiornamenti dei pacchetti o modifiche del provider che potrebbero aver spostato OVMF.

Se la VM non si avvia dopo una modifica del kernel

Aggiornamenti del kernel del guest o dell’initramfs possono richiedere rollback. Se avete snapshot, verificate la possibilità di un rollback; altrimenti avviate un ambiente di rescue e cambiate l’initrd o la versione del kernel.

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

Perché: gli aggiornamenti dei pacchetti possono fornire driver/moduli incompatibili. Un rollback è spesso la soluzione più rapida, se fattibile tempestivamente.

Se la rete o cloud‑init bloccano l’avvio

In Cloud‑Init‑basierten Images kann fehlerhafte Netzwerkkonfiguration den Boot verzögern oder stoppen (z. B. systemd‑timeout beim Anfordern einer DHCP‑Adresse). Prüfen Sie /etc/cloud/cloud.cfg und Netplan/ifupdown Konfigurationen innerhalb des Images.

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

Warum: Cloud‑Init kann Network‑Waiting verursachen; oft hilft eine Anpassung an eine statische oder tolerantere NetworkManager/Netplan Einstellung.

Wiederanlauf: VM an einer Rescue‑VM anhängen

Wenn Reparaturen im Image notwendig sind, ist das Anfügen der Disk an eine funktionierende Rescue‑VM die sicherste Methode.

# 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

Warum: So können Sie in der Rescue‑VM mit bekannten Tools das Dateisystem reparieren oder Logs lesen, ohne die Ziel-VM zu starten.

Wenn alles fehlschlägt: disk snapshot wiederherstellen und Rollback‑Plan

Halten Sie einen Rollback‑Pfad bereit: vorhandene Snapshots, Backups oder Storage‑Replikate. Beschreiben Sie vorab die minimal nötigen Schritte, um eine Service‑Wiederherstellung zu erreichen (z. B. VM an anderem Host starten, Disk aus Replica importieren).

Rollback‑Checkliste

• Gültigen Backup/Snapshot lokalisieren
• Platz und I/O auf Zielhost prüfen
• Disk importieren/RESTore auf separatem Host testen
• Service‑Tests durchführen (SSH, Anwendungssanity)
• Kommunikation: Downtime, Probleme, Rollback‑Zeitfenster

Typische Stolperfallen und wie man sie vermeidet

• Snapshot‑Ketten: Zu viele qcow2 Snapshots erhöhen Komplexität — konsolidieren Sie vorsichtig.
• Thin‑Provisioning: LVM/ZFS thin kann plötzlich voll laufen — Alerts konfigurieren.
• Inkompatible OVMF‑Versionen nach Host‑Upgrade — prüfen Sie OVMF‑Binaries.
• Fehlende Konsole: Ohne serielle Konsole sind Kernel‑Panik‑Meldungen nicht sichtbar — Konsole dauerhaft konfigurieren.
• Rechtschreibfehler in libvirt XML (Pfad, driver name) — immer dumpxml überprüfen.

Praxisbeispiel: qcow2‑Image hat Backing file missing

Symptom: VM startet nicht, qemu meldet 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

Warum: qcow2 kann mit einer backing file arbeiten; fehlt diese, ist das Image inkonsistent. qemu-img rebase entfernt die Verknüpfung zur backing file, das funktioniert nur, wenn die Daten selbstständig korrekt sind — daher vorher Backup.

Monitoring‑ und Präventionshinweise

Um zukünftige Vorfälle zu vermeiden, sollten Sie folgende Punkte in Betrieb nehmen:

• Alerting für Storage‑Fill (LVM/ZFS/Thin/Datastore)
• Regelmäßige Scrubs/Checks (z. B. ZFS scrub, Ceph health checks)
• Automatisierte Test‑RESTores in Wartungsintervallen
• Serielle Konsole als Standard in VM‑Templates
• Dokumentierte Recovery‑Runbooks für kritische VMs

Fazit und Prioritätenliste für die Fehleranalyse

Se una KVM‑VM non avvia più, proceda in modo strutturato: servizi dell’host, storage, configurazione della VM, console e integrità del disco. Lavori sempre su copie, documenti ogni passaggio e predisponga un’opzione di rollback. Nella maggior parte dei casi l’errore si risolve con una combinazione di analisi in sola lettura (guestmount/guestfish), riparazione del filesystem e, se necessario, rigenerazione di initramfs/GRUB.

Se desidera una checklist rapida, inizi con questi passaggi:

1. Controllare i log e i servizi dell’host (libvirtd/qemu, dmesg)
2. Verificare il backend di storage (LVM/ZFS/Ceph/NFS)
3. Controllare l’XML della VM e il percorso del disco
4. Attivare la console seriale e leggere i log
5. Montare l’immagine in sola lettura e verificare i contenuti
6. Su una copia: fsck, rigenerare initramfs e reinstallare GRUB

Questo articolo vuole essere un’introduzione pratica al runbook: tecnicamente preciso, con comandi concreti e sempre con attenzione alla sicurezza operativa e alle strategie di ripristino.