Debuguer une VM Incus bloquée au boot (emergency mode)

Votre VM Incus apparaît RUNNING dans incus list, mais incus exec et SSH ne répondent plus ? Quand l'agent invité est mort, c'est que l'OS de la VM n'a pas fini de booter : elle est très probablement bloquée en emergency mode. La réponse courte : on ne passe plus par incus exec (qui exige l'agent), on capture la console série avec incus console, et si cela ne suffit pas, on monte le disque de la VM depuis l'hôte pour lire son journal systemd hors-ligne. Ce guide déroule ce diagnostic de bout en bout, jusqu'à un cas réel où un durcissement a briqué le boot EFI.

TL;DR, les 3 commandes clés

# 1. Capturer la console serie d'une VM bloquee (pty force)
timeout 14 script -qec 'incus console <vm>' /dev/null </dev/null 2>&1 | tail -45

# 2. Monter le disque de la VM (backend ZFS) depuis l'hote
incus stop <vm> --force
sudo zfs set volmode=dev <pool>/virtual-machines/<vm>.block
sudo kpartx -av /dev/zd0 && sudo mount -o ro /dev/mapper/zd0p2 /mnt/vm

# 3. Lire le journal du boot echoue hors-ligne
sudo journalctl -D /mnt/vm/var/log/journal --list-boots
sudo journalctl -D /mnt/vm/var/log/journal -b <offset> -p err --no-pager

Ce que vous allez apprendre

• Distinguer un agent mort d'un simple souci SSH : pourquoi une VM RUNNING reste injoignable.
• Capturer la console série d'une VM qui ne répond plus, malgré l'absence de vrai TTY.
• Monter le disque d'une VM stoppée depuis l'hôte (ZFS, dir, qcow2) pour lire son journal.
• Lire le journalctl hors-ligne d'un boot échoué avec journalctl -D.
• Analyser un cas réel où un sysctl de durcissement a cassé le montage /boot/efi.
• Mettre en place les filets de sécurité : snapshots, journald persistant, break-glass root.

Prérequis

• Un hôte Incus avec au moins une VM (pas un conteneur).
• Un accès root sur l'hôte (les opérations de montage disque l'exigent).
• Des notions de systemd (cibles, unités) et de partitionnement Linux.

Journald persistant : à activer AVANT l'incident

La méthode du journal hors-ligne ne fonctionne que si le journal systemd de la VM est persistant (Storage=persistent, ou le répertoire /var/log/journal/ existe). Sinon, journald garde tout en RAM et le journal du boot échoué est perdu au reboot. Activez-le dès la création de vos VM de lab.

Le symptôme : VM RUNNING mais injoignable

Vous redémarrez une VM, puis plus rien. incus list la montre pourtant bien démarrée :

incus list <vm>
# +------+---------+------+------+-----------------+-----------+
# | NAME | STATE   | IPV4 | IPV6 | TYPE            | SNAPSHOTS |
# +------+---------+------+------+-----------------+-----------+
# | <vm> | RUNNING |      |      | VIRTUAL-MACHINE | 0         |
# +------+---------+------+------+-----------------+-----------+

Notez l'absence d'adresse IPv4 : l'OS n'a pas configuré son réseau. Une tentative d'exécution confirme le diagnostic :

incus exec <vm> -- whoami
# Error: VM agent isn't currently running

Le RUNNING d'Incus signifie seulement que QEMU fait tourner la machine. Il ne dit rien sur l'état du système invité. Ici, l'agent (incus-agent) n'a jamais démarré : l'OS s'est arrêté en cours de route. Ce n'est pas un problème SSH, c'est un boot qui n'aboutit pas (brick ou hang).

Agent mort = OS non booté

L'incus-agent ne démarre qu'une fois le système invité suffisamment avancé dans son boot. S'il est absent, inutile de chercher du côté de sshd ou du réseau : la VM est restée en amont, souvent en emergency mode ou figée sur un start job.

Pourquoi les réflexes habituels échouent sur une VM

Sur un conteneur Incus, le dépannage est direct. Sur une VM, plusieurs commandes habituelles tombent à plat, car elles supposent un invité fonctionnel ou un vrai terminal.

Commande	Sur une VM bloquée	Pourquoi
incus exec <vm>	VM agent isn't currently running	exige l'agent, donc un OS booté
incus console <vm> --show-log	log série vide ou partiel	le tampon série n'est pas peuplé comme le log d'un conteneur
incus info <vm> --show-log	peu exploitable pour une VM	pas le détail du boot systemd
incus console <vm> en pipe	inappropriate ioctl for device	pas de vrai TTY dans un pipe

Glissez pour voir

L'incus exec est mort avec l'agent. Le --show-log, très utile pour un conteneur, ne donne pas le journal interne du boot d'une VM : il faut donc une autre approche. Et rediriger incus console dans un pipe échoue, car la commande réclame un pseudo-terminal.

incus console --show-log : pensé pour les conteneurs

Pour un conteneur, incus console <nom> --show-log affiche le journal de la console, très pratique. Sur une VM, ce log série est souvent vide ou partiel, et n'y figure pas le détail du boot systemd. Pour une VM, on attache plutôt la console série interactive (section suivante), puis on bascule sur le journal hors-ligne quand il faut le détail.

Niveau 1 : capturer la console série

Quand vous voulez simplement voir l'écran de la VM (le message d'erreur du boot), attachez la console série. Le piège : incus console exige un pseudo-terminal, donc une redirection naïve échoue. On force un pty avec script :

timeout 14 script -qec 'incus console <vm>' /dev/null </dev/null 2>&1 | tail -45

• script -qec '...' /dev/null exécute la commande dans un pty sans enregistrer de fichier (-q silencieux, -e propage le code de sortie, -c lance la commande).
• timeout 14 coupe au bout de 14 secondes : assez pour capturer l'écran courant.
• tail -45 ne garde que les dernières lignes, là où s'affiche l'état final.

Ce que vous lirez, selon la panne :

You are in emergency mode. After logging in, type "journalctl -xb" to view
system logs, "systemctl reboot" to reboot, or "exit" to continue bootup.

ou un start job qui ne se termine pas :

[*** ] A start job is running for /boot/efi (1min 30s / no limit)

ou encore un kernel panic. Pour détacher la console interactive proprement, tapez Ctrl+a puis q.

Les limites de la console série

La console série n'a pas de scrollback : les lignes [FAILED] et Dependency failed défilent et sont perdues. Et un login sulogin scripté n'est pas fiable (saisie no-echo du mot de passe via le pty). Pour le détail complet et reproductible du boot, passez au journal hors-ligne.

Niveau 2 : lire le journal hors-ligne en montant le disque

C'est le bon réflexe. Plutôt que de lutter avec une console aveugle, on stoppe la VM, on monte son disque depuis l'hôte et on lit son journal systemd tranquillement. La marche à suivre dépend du backend de stockage.

Identifiez d'abord le driver :

incus storage list
# +---------+--------+-------------+---------+
# | NAME    | DRIVER | DESCRIPTION | USED BY |
# +---------+--------+-------------+---------+
# | default | zfs    |             | 12      |
# +---------+--------+-------------+---------+

ZFS (zvol)

Sur ZFS, le disque de la VM est un zvol. Une fois la VM stoppée, ce zvol est en volmode=none : aucun device /dev/zdN n'est exposé. On l'expose, on lit ses partitions avec kpartx, puis on monte la racine en lecture seule :

incus stop <vm> --force

# Identifier le zvol du disque (suffixe .block)
zfs list -t volume | grep <vm>
Z=<pool>/virtual-machines/<vm>.block

# Exposer le zvol comme device bloc
sudo zfs set volmode=dev "$Z"

# kpartx cree les mappings de partitions (/dev/mapper/zd0p1, zd0p2...)
sudo kpartx -av /dev/zd0

# Monter la racine en lecture seule (p2 = ext4 racine, p1 = EFI vfat)
sudo mkdir -p /mnt/vm
sudo mount -o ro /dev/mapper/zd0p2 /mnt/vm

volmode=dev masque les partitions, d'ou kpartx

volmode=dev expose bien /dev/zd0, mais cache ses partitions : vous n'aurez pas de /dev/zd0p1 automatiquement. C'est exactement pourquoi kpartx -av est nécessaire (ou volmode=full, qui les exposerait, mais reste moins prévisible). partprobe seul ne crée pas toujours les nodes.

Après diagnostic, nettoyez dans l'ordre inverse :

sudo umount /mnt/vm
sudo kpartx -d /dev/zd0
sudo zfs set volmode=none "$Z"

dir (image raw)

Sur le backend dir, le disque est une image raw (root.img). On l'attache à un loop device avec scan des partitions (-P) :

incus stop <vm> --force

IMG=/var/lib/incus/storage-pools/default/virtual-machines/<vm>/root.img
sudo losetup -fP "$IMG"
losetup -j "$IMG"          # retrouver le loopN attribue (ex. /dev/loop0)

sudo mkdir -p /mnt/vm
sudo mount -o ro /dev/loop0p2 /mnt/vm

Nettoyage :

sudo umount /mnt/vm
sudo losetup -d /dev/loop0

qcow2

Pour une image qcow2, on passe par le Network Block Device :

incus stop <vm> --force

sudo modprobe nbd max_part=8
sudo qemu-nbd --connect=/dev/nbd0 <image>.qcow2

sudo mkdir -p /mnt/vm
sudo mount -o ro /dev/nbd0p2 /mnt/vm

Nettoyage :

sudo umount /mnt/vm
sudo qemu-nbd -d /dev/nbd0

Une fois la racine montée, lisez le journal du boot échoué. Sur un disque monté, le « boot courant » n'est pas forcément le dernier : listez les boots, puis ciblez l'offset voulu.

# Lister les boots enregistres
sudo journalctl -D /mnt/vm/var/log/journal --list-boots
# IDX BOOT ID    FIRST ENTRY        LAST ENTRY
#  -1 a1b2...    2026-06-29 09:14   2026-06-29 09:31
#   0 c3d4...    2026-06-29 09:32   2026-06-29 09:32   <- le boot echoue

# Lire les erreurs de ce boot
sudo journalctl -D /mnt/vm/var/log/journal -b 0 -p err --no-pager

# Trouver la cause directement
sudo journalctl -D /mnt/vm/var/log/journal -b 0 --no-pager \
  | grep -iE 'Dependency failed|Failed to mount|emergency'

Le grep final remonte presque toujours la chaîne de causalité : une unité qui échoue, une dépendance non satisfaite, puis la bascule en emergency.

Étude de cas : un durcissement qui brique le boot EFI

Voici un cas réel, reproductible, qui illustre toute la chaîne. Le journal hors-ligne révèle ceci :

systemd[1]: Mounting boot-efi.mount - /boot/efi...
mount[420]: mount: /boot/efi: unknown filesystem type 'vfat'.
systemd[1]: boot-efi.mount: Mount process exited, code=exited, status=32
systemd[1]: Failed to mount boot-efi.mount - /boot/efi.
systemd[1]: Dependency failed for local-fs.target - Local File Systems.
systemd[1]: Reached target emergency.target - Emergency Mode.

La racine du problème : un durcissement avait posé kernel.modules_disabled=1 via un drop-in /etc/sysctl.d/. Or ce sysctl est un interrupteur à sens unique : une fois à 1, plus aucun module noyau ne peut être chargé, et on ne peut pas revenir à 0 sans reboot.

systemd applique les sysctl très tôt au boot, via systemd-sysctl. Son ordonnancement par rapport au montage de /boot/efi n'est pas garanti : les deux convergent vers sysinit.target sans ordre mutuel strict. Si kernel.modules_disabled=1 est appliqué avant que le montage de /boot/efi ne déclenche le chargement du module vfat, et si ce module n'est pas déjà chargé, alors le montage échoue. Pas de vfat, pas d'EFI montée, local-fs.target en échec, et bascule en emergency mode.

La leçon : appliquer un sysctl one-way TARD

Un sysctl de désactivation à sens unique comme kernel.modules_disabled ne doit jamais vivre dans un drop-in sysctl.d appliqué au boot. Posez-le tard, via une unité systemd oneshot ordonnancée After=local-fs.target (voire après le réseau), une fois tous les modules nécessaires déjà chargés. Voir le durcissement des modules du noyau Linux et la configuration sysctl.

Piège bonus : root verrouillé = emergency inaccessible

Sur les images cloud, le compte root est souvent verrouillé (* dans /etc/shadow). Conséquence : l'emergency mode devient inaccessible, car sulogin refuse un compte sans mot de passe. Vous voyez l'invite, mais ne pouvez pas vous connecter. Prévoyez toujours un break-glass (compte de récupération ou mot de passe GRUB documenté).

Récupération et filet de sécurité

Avant toute opération risquée sur une VM, prenez un snapshot. C'est votre marche arrière :

# Avant un changement de boot risque
incus snapshot create <vm> avant-durcissement

# Revenir en arriere si la VM ne boote plus
incus snapshot restore <vm> avant-durcissement

Le piège du snapshot trop ancien

Un restore ramène la VM exactement à l'état du snapshot. Si vous avez pris le snapshot avant d'installer un paquet (un agent d'audit, par exemple), le restore le fait disparaître. Prenez le snapshot juste avant le changement à tester, pas en début de session.

Côté accès, ne verrouillez jamais root sans laisser une voie de secours. L'emergency mode est précisément le moment où vous en avez besoin :

• un compte de récupération local avec mot de passe,
• ou un mot de passe GRUB documenté pour éditer la ligne de commande noyau au boot.

Prévention : la checklist

Le meilleur debug est celui qu'on n'a pas à faire. Trois réflexes évitent la majorité de ces blocages :

1. Journald persistant dès le départ

   Sur vos VM de lab, activez Storage=persistent (ou créez /var/log/journal/) dès la création. Sans cela, le journal du boot échoué part en fumée au reboot.

2. Tester les changements de boot sur une VM jetable

   Tout ce qui touche au boot (/etc/fstab, ligne de commande noyau, sysctl à sens unique) se teste sur une VM jetable protégée par un snapshot, jamais directement sur une machine qui compte.

3. Trouver le fautif par la trace, pas par reboots à l'aveugle

   Privilégiez le dry-run de votre configuration (état convergé sans reboot) pour repérer un changement dangereux avant qu'il ne brique le boot, plutôt que d'enchaîner les redémarrages au hasard.

À retenir

• Une VM RUNNING sans agent n'a pas fini de booter : ce n'est pas un souci SSH.
• incus exec exige l'agent ; sur une VM bloquée, il renvoie VM agent isn't currently running.
• Pour une VM, --show-log donne un log série souvent vide : on capture la console série (incus console, détacher avec Ctrl+a q), forcée dans un pty via script.
• Le bon réflexe : stopper la VM, monter son disque depuis l'hôte (ZFS via volmode=dev + kpartx, dir via losetup -fP, qcow2 via qemu-nbd) et lire le journal avec journalctl -D.
• volmode=dev masque les partitions du zvol, d'où le recours à kpartx.
• Un sysctl à sens unique comme kernel.modules_disabled=1 posé trop tôt peut casser un montage (/boot/efi en vfat) et provoquer l'emergency mode.
• Snapshots, journald persistant et break-glass root sont vos trois filets de sécurité.

FAQ : questions fréquentes sur le debug d'une VM Incus

Pourquoi incus exec ne fonctionne pas sur ma VM ?

incus exec passe par l'agent invité (incus-agent), qui ne démarre qu'une fois l'OS booté. Si la VM est bloquée au boot ou en emergency mode, l'agent est mort et la commande renvoie Error: VM agent isn't currently running. Ce n'est pas un souci SSH, mais un boot qui n'aboutit pas.

Comment lire le journal d'une VM Incus éteinte ?

On monte le disque de la VM depuis l'hôte puis on lit son journal avec journalctl -D. Après incus stop --force, on expose le disque (ZFS : volmode=dev + kpartx ; dir : losetup -fP ; qcow2 : qemu-nbd), on monte la racine en lecture seule, puis journalctl -D /mnt/vm/var/log/journal --list-boots.

incus console --show-log fonctionne-t-il sur une VM ?

Pas utilement. Sur un conteneur, --show-log affiche le journal de la console. Sur une VM, ce log série est souvent vide et ne contient pas le détail du boot systemd. On attache plutôt la console série interactive avec incus console <vm> (détachement Ctrl+a q), puis on lit le journal hors-ligne.

Comment monter le disque d'une VM Incus stockée en ZFS ?

Après incus stop --force, le disque est un zvol en volmode=none. On l'expose avec zfs set volmode=dev sur le dataset .block, ce qui crée /dev/zd0 mais masque ses partitions. On les rend visibles avec kpartx -av /dev/zd0, puis on monte /dev/mapper/zd0p2 en lecture seule.

Pourquoi ma VM Incus tombe-t-elle en emergency mode au boot ?

L'emergency mode survient quand local-fs.target échoue, souvent un montage impossible (/etc/fstab erroné, partition absente). Cas classique : kernel.modules_disabled=1 appliqué trop tôt empêche le module vfat, cassant le montage de /boot/efi. Le journal hors-ligne révèle la cause.

Prochaines étapes

Gestion des instances Incus Créer, configurer et piloter vos conteneurs et VM Incus au quotidien.

Durcir les modules du noyau Maîtriser modules_disabled et le blocage de modules sans casser le boot.

Configuration sysctl Appliquer des paramètres noyau de durcissement au bon moment.

Lire les journaux avec journalctl Exploiter journalctl, ses filtres et l'option -D pour un système hors-ligne.

×

📖 Voir la documentation →