virsh : les 15 commandes essentielles pour gérer vos VMs KVM

virsh est l'outil CLI standard pour piloter libvirt — il gère les VMs (domains), les réseaux virtuels et le stockage. Ces 15 commandes couvrent les opérations quotidiennes les plus fréquentes sur vos VMs KVM.

libvirt moderne : démons modulaires

Depuis RHEL 9 / Fedora 34+, libvirt utilise des démons séparés (virtqemud, virtnetworkd, virtstoraged) au lieu du monolithique libvirtd. Les deux modes coexistent, mais les commandes de ce guide restent identiques.

Ce que vous allez apprendre

Compétence	Commandes clés
Voir l'état des VMs	list, dominfo, domstate
Contrôler le cycle de vie	start, shutdown, destroy, reboot
Diagnostiquer une VM	domifaddr, domblklist, domiflist
Configurer une VM	edit, dumpxml, autostart
Gérer réseau et stockage	net-*, pool-*, vol-*

Glissez pour voir

Pré-requis

Ce guide suppose que vous avez :

• KVM/libvirt installé (voir Installation)
• Une VM existante (créée avec Créer une VM ou Cloud-init)
• Accès à un terminal avec les droits libvirt

Vérification rapide

virsh list --all

Si vous voyez au moins une VM, vous êtes prêt !

Modèle mental : comment fonctionne virsh

🧠 Modèle mental — Comment fonctionne virsh

virsh = Interface CLI pour libvirt → Gérer VMs, réseaux, stockage

Points clés

• virsh gère 3 types de ressources : domains (VMs), networks, storage pools
• Un "domain" = une VM dans le vocabulaire libvirt
• Les commandes dom* concernent les VMs (dominfo, domstate, domblklist...)
• Les commandes net-* concernent les réseaux (net-list, net-info...)
• Les commandes pool-*/vol-* concernent le stockage
• --all affiche aussi les ressources arrêtées (sinon : actives uniquement)

Règles d'or

1

Toujours vérifier l'état avant d'agir virsh list --all montre l'état de toutes les VMs. Ne pas démarrer une VM déjà running.

2

shutdown > destroy shutdown = arrêt propre (ACPI). destroy = couper le courant. Privilégier shutdown.

3

dumpxml pour comprendre, edit pour modifier dumpxml montre la config complète. edit ouvre l'éditeur pour modifier.

Vocabulaire essentiel

domain

Une VM dans le vocabulaire libvirt

pool

Conteneur de stockage (répertoire, LVM, ZFS...)

volume

Un disque individuel dans un pool

network

Réseau virtuel (NAT, bridge...)

running

VM en cours d'exécution

shut off

VM arrêtée

📚 Pour aller plus loin — 6 options avancées

paused

VM suspendue (gelée en mémoire)

persistent

VM définie de façon permanente

transient

VM temporaire (disparaît à l'arrêt)

autostart

Démarrage automatique au boot de l'hôte

vCPU

CPU virtuel assigné à la VM

vNIC

Interface réseau virtuelle

L'analogie du chef d'orchestre

Pensez à virsh comme un chef d'orchestre :

Élément	Analogie	virsh
Musiciens	Les VMs	domains
Partitions	La config de chaque VM	dumpxml
"Commencez !"	Démarrer	start
"Stop !"	Arrêter	shutdown
"Comment ça va ?"	État	dominfo
"Pause"	Suspendre	suspend

Glissez pour voir

Le chef ne joue pas lui-même — il coordonne. virsh ne fait pas tourner les VMs, il parle à libvirt qui lui-même pilote QEMU/KVM.

Le vocabulaire libvirt

Terme libvirt	Signification	Équivalent courant
domain	Machine virtuelle	VM
pool	Conteneur de stockage	Dossier ou LV
volume	Disque dans un pool	Fichier qcow2
network	Réseau virtuel	Bridge ou NAT
running	VM en cours	Allumée
shut off	VM arrêtée	Éteinte
paused	VM suspendue	Gelée en RAM

Glissez pour voir

Pourquoi « domain » ?

Le terme vient de Xen, où chaque VM est un "domaine". libvirt a gardé ce vocabulaire pour rester générique (il supporte aussi Xen, LXC, VMware...).

Les patterns essentiels

Ces patterns couvrent les opérations virsh du quotidien, de la simple consultation d'état à la modification de configuration. Chacun est détaillé ci-dessous avec sa formule, un exemple concret et les pièges associés.

Pattern 1 : Lister les VMs

La commande de base pour voir l'état de vos VMs :

Lister toutes les VMs

virsh list --all

Sortie typique

 Id   Name           State
------------------------------
 2    ubuntu-cloud   running
 -    ubuntu-test    shut off
 -    ubuntu-uefi    shut off

Décryptage :

Colonne	Signification
Id	Numéro d'instance (uniquement si running)
Name	Nom de la VM (utilisé dans toutes les commandes)
State	running, shut off, paused, crashed...

Glissez pour voir

Sans --all, les VMs arrêtées sont invisibles

virsh list      # Montre UNIQUEMENT les VMs running
virsh list --all  # Montre TOUTES les VMs

Pattern 2 : Informations détaillées

Pour diagnostiquer une VM, dominfo donne une vue synthétique :

Informations complètes

virsh dominfo ubuntu-cloud

Sortie typique

Id:             2
Name:           ubuntu-cloud
UUID:           7e4a6b3c-9d8e-4f5a-b2c1-d3e4f5a6b7c8
OS Type:        hvm
State:          running
CPU(s):         2
CPU time:       45.3s
Max memory:     2097152 KiB
Used memory:    2097152 KiB
Persistent:     yes
Autostart:      disable
Managed save:   no
Security model: apparmor
Security DOI:   0
Security label: libvirt-7e4a6b3c-...,enforce

Décryptage :

Champ	Signification
Id	Numéro d'instance (- si arrêtée)
State	État actuel
CPU(s)	Nombre de vCPU
Max memory	RAM allouée (en KiB)
Persistent	yes = VM définie, no = transient
Autostart	Démarre au boot de l'hôte

Glissez pour voir

Pattern 3 : Cycle de vie

Les 4 commandes pour contrôler une VM :

Démarrer

virsh start ubuntu-cloud

Domain 'ubuntu-cloud' started

Arrêter (propre)

virsh shutdown ubuntu-cloud

Domain 'ubuntu-cloud' is being shutdown

Signal ACPI → arrêt propre (comme appuyer sur le bouton power).

Arrêter (forcé)

virsh destroy ubuntu-cloud

Domain 'ubuntu-cloud' destroyed

Équivalent à couper le courant. À éviter sauf blocage.

Redémarrer

virsh reboot ubuntu-cloud

Domain 'ubuntu-cloud' is being rebooted

Redémarrage propre via ACPI.

destroy ≠ supprimer

destroy n'efface pas la VM ! C'est un arrêt brutal. Pour supprimer définitivement une VM : virsh undefine ubuntu-cloud

Pattern 4 : Obtenir l'IP d'une VM

Question fréquente : "Comment je SSH sur ma VM ?"

domifaddr dispose de trois sources différentes, selon votre configuration :

Source lease (DHCP libvirt)

Le plus fiable si réseau libvirt + DHCP

virsh domifaddr ubuntu-cloud --source lease

Sortie typique

 Name       MAC address          Protocol     Address
-------------------------------------------------------------------------------
 vnet1      52:54:00:49:47:a3    ipv4         192.168.122.91/24

Fonctionne si la VM utilise un réseau libvirt avec DHCP (réseau default).

Source agent

Si qemu-guest-agent est installé dans la VM

virsh domifaddr ubuntu-cloud --source agent

Sortie typique

 Name       MAC address          Protocol     Address
-------------------------------------------------------------------------------
 eth0       52:54:00:49:47:a3    ipv4         192.168.122.91/24
 lo         00:00:00:00:00:00    ipv4         127.0.0.1/8

Le plus complet (montre toutes les interfaces), mais nécessite qemu-guest-agent actif.

Source arp

Si la VM est sur le même L2 que l'hôte

virsh domifaddr ubuntu-cloud --source arp

Interroge la table ARP de l'hôte. Fonctionne sans agent si la VM a déjà communiqué.

Alternative : interroger dnsmasq directement

Baux DHCP du réseau libvirt

virsh net-dhcp-leases default

Sortie typique

 Expiry Time           MAC address         Protocol   IP address       Hostname
-----------------------------------------------------------------------------------
 2024-01-15 14:32:45   52:54:00:49:47:a3   ipv4       192.168.122.91/24   ubuntu-cloud

Quelle source choisir ?

Source	Prérequis	Fiabilité
--source lease	Réseau libvirt + DHCP	★★★ Recommandé
--source agent	qemu-guest-agent installé	★★★ Le plus complet
--source arp	VM active + même L2	★★ Dépannage
net-dhcp-leases	Réseau libvirt	★★★ Alternative fiable

Glissez pour voir

Pattern 5 : Suspendre et reprendre

Suspendre une VM la "gèle" en mémoire (économise CPU) :

Suspendre

virsh suspend ubuntu-cloud

Domain 'ubuntu-cloud' suspended

Vérifier l'état

virsh domstate ubuntu-cloud

paused

Reprendre

virsh resume ubuntu-cloud

Domain 'ubuntu-cloud' resumed

Pattern 6 : Voir les disques et interfaces

Pour diagnostiquer ou vérifier la configuration :

Disques

virsh domblklist ubuntu-cloud

 Target   Source
-------------------------------------------------
 vda      /var/lib/libvirt/images/ubuntu-cloud.qcow2
 sda      /var/lib/libvirt/images/seed.iso

Interfaces réseau

virsh domiflist ubuntu-cloud

 Interface   Type      Source    Model    MAC
------------------------------------------------------------
 vnet1       network   default   virtio   52:54:00:49:47:a3

Mémoire

virsh dommemstat ubuntu-cloud

actual 2097152
swap_in 0
swap_out 0
major_fault 512
minor_fault 1234567
unused 1884632
available 2005944
usable 1876544
last_update 1705312345
disk_caches 98304
hugetlb_pgalloc 0
hugetlb_pgfail 0
rss 2150400

Pattern 7 : Exporter et sauvegarder

Sauvegarder la configuration XML (pour clonage ou backup) :

Exporter vers fichier

virsh dumpxml ubuntu-cloud > ubuntu-cloud-backup.xml

Créer une VM depuis un XML

virsh define ubuntu-cloud-backup.xml

dumpxml ne sauvegarde pas les données

Le XML contient uniquement la configuration (CPU, RAM, disques...). Les données sont dans les fichiers qcow2, à sauvegarder séparément.

Pattern 8 : Modifier la configuration

Pour changer CPU, RAM, ou autres paramètres :

Éditer la config

virsh edit ubuntu-cloud

Cela ouvre l'éditeur par défaut avec le XML de la VM.

Redémarrage requis

Les modifications via edit s'appliquent au prochain démarrage. Pour une VM running, il faut shutdown puis start.

Exemple : augmenter la RAM de 2Go à 4Go

Dans le XML, trouvez :

<memory unit='KiB'>2097152</memory>
<currentMemory unit='KiB'>2097152</currentMemory>

Changez en :

<memory unit='KiB'>4194304</memory>
<currentMemory unit='KiB'>4194304</currentMemory>

Puis redémarrez la VM.

Les pièges classiques

Ces six erreurs reviennent constamment chez les débutants comme chez les administrateurs pressés. Les connaître évite des pertes de données et des heures de diagnostic.

Piège n°1 : destroy ne supprime rien

❌ Ce que beaucoup croient

virsh destroy ubuntu-cloud  # "Je supprime la VM"

✅ Ce qui se passe vraiment

virsh destroy ubuntu-cloud  # Arrêt forcé (VM toujours définie)
virsh undefine ubuntu-cloud # Supprime uniquement la définition XML
# Les disques restent sur le système !

Terminologie libvirt

Commande	Action	Données
destroy	Coupe le courant (arrêt brutal)	Préservées
undefine	Supprime la définition XML	Disques conservés
undefine --remove-all-storage	Supprime définition + volumes	Disques supprimés

Glissez pour voir

Pour supprimer complètement une VM :

Suppression complète (définition + disques)

# D'abord, vérifier les volumes attachés
virsh domblklist ubuntu-cloud

# Suppression avec les volumes (IRRÉVERSIBLE)
virsh undefine ubuntu-cloud --remove-all-storage

--remove-all-storage : attention aux volumes partagés

--remove-all-storage supprime tous les volumes attachés. Si un volume est partagé entre plusieurs VMs, les autres VMs seront impactées. Vérifiez avec domblklist avant.

Pour un contrôle fin, utilisez --storage vda pour cibler un seul volume.

Piège n°2 : session vs system

Symptôme : VMs différentes selon sudo

virsh list --all         # Montre VM-A
sudo virsh list --all    # Montre VM-B, VM-C

Explication : libvirt a deux "mondes" séparés :

• qemu:///session — VMs de l'utilisateur (sans sudo, stockées dans ~/.local/share/libvirt)
• qemu:///system — VMs système (avec sudo, dans /var/lib/libvirt)

Solution 1 (explicite, recommandée) : spécifier l'URI à chaque commande

Toujours savoir où on travaille

virsh -c qemu:///system list --all   # VMs système
virsh -c qemu:///session list --all  # VMs utilisateur

Solution 2 (par défaut) : configurer l'URI une fois

~/.bashrc ou ~/.zshrc

export LIBVIRT_DEFAULT_URI="qemu:///system"

Attention aux scripts

Si vous utilisez LIBVIRT_DEFAULT_URI, vos scripts hériteront de cette variable. Préférez -c qemu:///system explicite dans les scripts pour éviter les surprises.

Piège n°3 : shutdown qui ne répond pas

virsh shutdown ubuntu-cloud
# ... rien ne se passe, la VM reste running

Cause : shutdown envoie un signal ACPI. Si la VM n'a pas de support ACPI ou si le système invité l'ignore, rien ne se passe.

Solutions :

1. Attendre 30 secondes (le guest peut être lent)
2. Vérifier que le package acpid est installé dans la VM
3. En dernier recours : virsh destroy

Piège n°4 : VMs invisibles sans --all

virsh list

Symptôme : la liste des VMs est vide ou incomplète, votre VM n'apparaît pas.

Cause : par défaut, list n'affiche que les VMs running. Une VM shut off reste invisible.

virsh list --all

Piège n°5 : domifaddr ne montre aucune IP

virsh domifaddr ubuntu-cloud

Symptôme : la table des adresses est vide, aucune IP affichée.

Cause : domifaddr s'appuie sur qemu-guest-agent ou sur un bail DHCP actif. Sans l'un des deux, il ne peut rien retourner.

virsh net-dhcp-leases default

Piège n°6 : edit sur une VM running

virsh edit ubuntu-cloud

Symptôme : la configuration est modifiée, mais la VM continue d'utiliser les anciennes valeurs.

Cause : virsh edit modifie la configuration persistante, pas la VM en cours d'exécution. Les changements ne s'appliquent qu'au prochain démarrage.

virsh shutdown ubuntu-cloud && virsh start ubuntu-cloud

Logs et dépannage

Pour diagnostiquer un problème libvirt, consultez les logs des démons. Selon votre distribution, libvirt utilise soit le démon monolithique (libvirtd), soit des démons modulaires.

Démons modulaires (RHEL 9+, Fedora 34+)

Vérifier l'état des services

systemctl status virtqemud virtnetworkd virtstoraged

Logs en temps réel

# Problèmes de VMs (QEMU)
journalctl -u virtqemud -f

# Problèmes de réseau virtuel
journalctl -u virtnetworkd -f

# Problèmes de stockage/pools
journalctl -u virtstoraged -f

Démon monolithique (Ubuntu, Debian)

Vérifier l'état

systemctl status libvirtd

Logs en temps réel

journalctl -u libvirtd -f

Quel mode utilisez-vous ?

# Si virtqemud existe et est actif → démons modulaires
systemctl is-active virtqemud 2>/dev/null && echo "Modulaire" || echo "Monolithique"

Fichiers de logs additionnels :

Fichier	Contenu
/var/log/libvirt/qemu/<vm>.log	Logs QEMU de chaque VM
/var/log/libvirt/libvirtd.log	Log principal (si activé)

Glissez pour voir

Erreurs fréquentes

Quand virsh refuse de fonctionner, ces deux erreurs couvrent la grande majorité des cas rencontrés en début de prise en main.

Erreur	Cause probable	Solution
error: failed to connect to the hypervisor	Utilisateur absent du groupe libvirt, libvirtd arrêté, ou mauvais URI	Ajouter l'utilisateur au groupe : sudo usermod -aG libvirt $USER, puis vérifier avec virsh list --all
error: failed to get domain	Mauvais nom de VM, ou VM dans un autre URI (session vs system)	Lister les noms exacts avec virsh list --all (et sudo virsh list --all)

Glissez pour voir

Exercices flash (5 min)

Trois micro-exercices pour valider vos acquis :

1. Lister et identifier — Trouvez toutes vos VMs et leur état.

   virsh list --all
   virsh dominfo <nom-vm>

   ✓ Vous devez voir l'état (running/shut off) et la RAM allouée.

2. Cycle de vie — Démarrez, arrêtez proprement, redémarrez.

   virsh start <nom-vm>
   virsh shutdown <nom-vm>   # Attendre l'arrêt
   virsh start <nom-vm>

   ✓ La VM répond à shutdown ? Si non, vérifiez acpid dans la VM.

3. Trouver l'IP — Testez les différentes sources.

   virsh domifaddr <nom-vm> --source lease
   virsh net-dhcp-leases default

   ✓ Vous avez une IP ? Testez ssh user@<ip> pour confirmer.

Aller plus loin

Pour des exercices complets (snapshots, clonage, migration), consultez les guides dédiés K8 et K9.

Cheatsheet complète

À garder sous la main : les commandes virsh regroupées par usage — état, cycle de vie, configuration, réseau et stockage.

État et informations

Syntaxe	Signification	Exemple
virsh list --all	Lister toutes les VMs	virsh list --all
virsh dominfo <vm>	Infos complètes d'une VM	virsh dominfo ubuntu-cloud
virsh domstate <vm>	État uniquement	virsh domstate ubuntu-cloud
virsh domifaddr <vm>	Adresse IP de la VM	virsh domifaddr ubuntu-cloud
virsh domblklist <vm>	Disques attachés	virsh domblklist ubuntu-cloud
virsh domiflist <vm>	Interfaces réseau	virsh domiflist ubuntu-cloud

Glissez pour voir

Cycle de vie

Syntaxe	Signification	Exemple
virsh start <vm>	Démarrer	virsh start ubuntu-cloud
virsh shutdown <vm>	Arrêt propre (ACPI)	virsh shutdown ubuntu-cloud
virsh destroy <vm>	Arrêt forcé	virsh destroy ubuntu-cloud
virsh reboot <vm>	Redémarrer	virsh reboot ubuntu-cloud
virsh suspend <vm>	Mettre en pause	virsh suspend ubuntu-cloud
virsh resume <vm>	Reprendre	virsh resume ubuntu-cloud
virsh console <vm>	Console série (Ctrl+] pour sortir)	virsh console ubuntu-cloud

Glissez pour voir

Configuration

Syntaxe	Signification	Exemple
virsh dumpxml <vm>	Afficher la config XML	virsh dumpxml ubuntu-cloud
virsh edit <vm>	Éditer la config	virsh edit ubuntu-cloud
virsh autostart <vm>	Activer l'autostart	virsh autostart ubuntu-cloud
virsh autostart --disable <vm>	Désactiver l'autostart	virsh autostart --disable ubuntu-cloud
virsh define <fichier.xml>	Créer une VM depuis un XML	virsh define ubuntu.xml
virsh undefine <vm>	Supprimer la définition	virsh undefine ubuntu-cloud

Glissez pour voir

Réseau et stockage

Syntaxe	Signification	Exemple
virsh net-list --all	Lister les réseaux	virsh net-list --all
virsh net-dhcp-leases <net>	Baux DHCP d'un réseau	virsh net-dhcp-leases default
virsh net-info <net>	Info d'un réseau	virsh net-info default
virsh pool-list --all	Lister les pools de stockage	virsh pool-list --all
virsh vol-list <pool>	Lister les volumes d'un pool	virsh vol-list default
virsh pool-info <pool>	Info d'un pool	virsh pool-info default

Glissez pour voir

Commandes de diagnostic

Commande	Description
virsh vcpuinfo <vm>	Détails des vCPU (affinité, temps CPU)
virsh domtime <vm>	Horloge de la VM (requiert guest-agent)
virsh dommemstat <vm>	Statistiques mémoire détaillées

Glissez pour voir

Commandes avancées (guides dédiés)

À ne pas utiliser sans contexte

Ces commandes ont des prérequis importants (backend stockage, cohérence disque, permissions, réseau...). Consultez les guides dédiés avant de les utiliser en production.

Commande	Risque	Guide
migrate	Perte de données si mal configuré	K10 — Migration
snapshot-create-as	Incohérence si VM non quiescée	Snapshots
undefine --remove-all-storage	Suppression irréversible	Voir Danger Zone ci-dessus

Glissez pour voir

À retenir

Concept	Commande	Ce qu'elle fait
Voir	list --all	Toutes les VMs
Info	dominfo	Synthèse d'une VM
IP	domifaddr --source lease	Adresse réseau (ou agent)
Démarrer	start	Allumer
Arrêter	shutdown	Éteindre (propre)
Sauvegarder	dumpxml	Exporter la config

Glissez pour voir

Les 3 règles d'or :

1. Toujours --all — sinon vous ne voyez que les VMs running
2. shutdown avant destroy — arrêt propre d'abord
3. destroy ≠ delete — destroy arrête, undefine supprime la définition

Checklist de maîtrise

Vous maîtrisez virsh quand vous pouvez cocher chacun de ces points sans hésiter :

• Je sais lister toutes les VMs avec virsh list --all.
• Je sais obtenir les informations d'une VM avec dominfo.
• Je sais démarrer, arrêter et redémarrer une VM.
• Je sais trouver l'IP d'une VM.
• Je sais exporter et modifier la configuration XML.
• Je sais configurer l'autostart d'une VM.

Prochaines étapes

Snapshots et clones Sauvegarder et restaurer l'état de vos VMs.

Formation KVM complète Tous les modules de la formation.

Automatiser avec Ansible Piloter KVM avec community.libvirt.

×

📖 Voir la documentation →