
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.
Ce que vous allez apprendre
Section intitulée « 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-* |
Pré-requis
Section intitulée « 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
Modèle mental : comment fonctionne virsh
Section intitulée « 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
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
Section intitulée « 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 |
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
Section intitulée « 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 |
Les patterns essentiels
Section intitulée « Les patterns essentiels »Ces recettes couvrent les cas d'usage les plus fréquents. Cliquez sur un pattern pour voir la formule complète et un exemple prêt à copier.
Lister toutes les VMs Base Voir l'état de toutes les VMs (actives et arrêtées).
virsh list --all
virsh list --all virsh list --all -
--all— Inclut les VMs arrêtées -
(sans option)— Uniquement les VMs running
Informations complètes d'une VM Base Afficher CPU, RAM, état, UUID d'une VM.
virsh dominfo ubuntu-cloud
virsh dominfo <vm> virsh dominfo ubuntu-cloud -
<vm>— Nom ou ID de la VM
Démarrer / Arrêter une VM Base Contrôler le cycle de vie d'une VM.
virsh shutdown ubuntu-cloud
virsh start|shutdown|destroy|reboot <vm> virsh shutdown ubuntu-cloud -
start— Démarrer la VM -
shutdown— Arrêt propre (ACPI) -
destroy— Arrêt forcé (couper le courant) -
reboot— Redémarrer
Accéder à la console Base Se connecter au terminal de la VM.
virsh console ubuntu-cloud
virsh console <vm> virsh console ubuntu-cloud -
<vm>— Nom de la VM -
Ctrl+]— Pour sortir de la console
Obtenir l'IP d'une VM Base Afficher l'adresse IP d'une VM.
virsh domifaddr ubuntu-cloud
virsh domifaddr <vm> virsh domifaddr ubuntu-cloud -
<vm>— Nom de la VM -
--source agent— Via qemu-guest-agent (plus précis)
Démarrage automatique Base Configurer une VM pour démarrer au boot de l'hôte.
virsh autostart ubuntu-cloud
virsh autostart [--disable] <vm> virsh autostart ubuntu-cloud -
<vm>— Nom de la VM -
--disable— Désactiver l'autostart
Exporter la configuration XML Inter. Afficher la configuration complète d'une VM.
virsh dumpxml ubuntu-cloud > ubuntu-cloud.xml
virsh dumpxml <vm> virsh dumpxml ubuntu-cloud > ubuntu-cloud.xml -
<vm>— Nom de la VM -
> fichier.xml— Rediriger vers un fichier (sauvegarde)
Modifier la configuration Inter. Éditer le XML d'une VM dans l'éditeur.
virsh edit ubuntu-cloud
virsh edit <vm> virsh edit ubuntu-cloud -
<vm>— Nom de la VM -
EDITOR=vim— Choisir l'éditeur
Aucune recette ne correspond à votre recherche.
Pattern 1 : Lister les VMs
Section intitulée « Pattern 1 : Lister les VMs »La commande de base pour voir l’état de vos VMs :
virsh list --all Id Name State------------------------------ 2 ubuntu-cloud running - ubuntu-test shut off - ubuntu-uefi shut offDé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… |
Pattern 2 : Informations détaillées
Section intitulée « Pattern 2 : Informations détaillées »Pour diagnostiquer une VM, dominfo donne une vue synthétique :
virsh dominfo ubuntu-cloudId: 2Name: ubuntu-cloudUUID: 7e4a6b3c-9d8e-4f5a-b2c1-d3e4f5a6b7c8OS Type: hvmState: runningCPU(s): 2CPU time: 45.3sMax memory: 2097152 KiBUsed memory: 2097152 KiBPersistent: yesAutostart: disableManaged save: noSecurity model: apparmorSecurity DOI: 0Security label: libvirt-7e4a6b3c-...,enforceDé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 |
Pattern 3 : Cycle de vie
Section intitulée « Pattern 3 : Cycle de vie »Les 4 commandes pour contrôler une VM :
virsh start ubuntu-cloudDomain 'ubuntu-cloud' startedvirsh shutdown ubuntu-cloudDomain 'ubuntu-cloud' is being shutdownSignal ACPI → arrêt propre (comme appuyer sur le bouton power).
virsh destroy ubuntu-cloudDomain 'ubuntu-cloud' destroyedÉquivalent à couper le courant. À éviter sauf blocage.
virsh reboot ubuntu-cloudDomain 'ubuntu-cloud' is being rebootedRedémarrage propre via ACPI.
Pattern 4 : Obtenir l’IP d’une VM
Section intitulée « 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 :
virsh domifaddr ubuntu-cloud --source lease Name MAC address Protocol Address------------------------------------------------------------------------------- vnet1 52:54:00:49:47:a3 ipv4 192.168.122.91/24Fonctionne si la VM utilise un réseau libvirt avec DHCP (réseau default).
virsh domifaddr ubuntu-cloud --source agent 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/8Le plus complet (montre toutes les interfaces), mais nécessite qemu-guest-agent actif.
virsh domifaddr ubuntu-cloud --source arpInterroge la table ARP de l’hôte. Fonctionne sans agent si la VM a déjà communiqué.
Alternative : interroger dnsmasq directement
virsh net-dhcp-leases default 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-cloudPattern 5 : Suspendre et reprendre
Section intitulée « Pattern 5 : Suspendre et reprendre »Suspendre une VM la “gèle” en mémoire (économise CPU) :
virsh suspend ubuntu-cloudDomain 'ubuntu-cloud' suspendedvirsh domstate ubuntu-cloudpausedvirsh resume ubuntu-cloudDomain 'ubuntu-cloud' resumedPattern 6 : Voir les disques et interfaces
Section intitulée « Pattern 6 : Voir les disques et interfaces »Pour diagnostiquer ou vérifier la configuration :
virsh domblklist ubuntu-cloud Target Source------------------------------------------------- vda /var/lib/libvirt/images/ubuntu-cloud.qcow2 sda /var/lib/libvirt/images/seed.isovirsh domiflist ubuntu-cloud Interface Type Source Model MAC------------------------------------------------------------ vnet1 network default virtio 52:54:00:49:47:a3virsh dommemstat ubuntu-cloudactual 2097152swap_in 0swap_out 0major_fault 512minor_fault 1234567unused 1884632available 2005944usable 1876544last_update 1705312345disk_caches 98304hugetlb_pgalloc 0hugetlb_pgfail 0rss 2150400Pattern 7 : Exporter et sauvegarder
Section intitulée « Pattern 7 : Exporter et sauvegarder »Sauvegarder la configuration XML (pour clonage ou backup) :
virsh dumpxml ubuntu-cloud > ubuntu-cloud-backup.xmlvirsh define ubuntu-cloud-backup.xmlPattern 8 : Modifier la configuration
Section intitulée « Pattern 8 : Modifier la configuration »Pour changer CPU, RAM, ou autres paramètres :
virsh edit ubuntu-cloudCela ouvre l’éditeur par défaut avec le XML de la VM.
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
Section intitulée « Les pièges classiques »Ces erreurs courantes peuvent faire perdre du temps ou causer des dégâts. Les pièges les plus critiques sont affichés en premier.
destroy ≠ supprimer virsh destroy ubuntu-cloud pour "supprimer" la VM
Danger
virsh destroy ubuntu-cloud pour "supprimer" la VM
virsh undefine ubuntu-cloud --remove-all-storage VMs invisibles sans --all virsh list — ma VM n'apparaît pas
Attention
virsh list — ma VM n'apparaît pas
virsh list --all session vs system VMs différentes avec et sans sudo
Attention
VMs différentes avec et sans sudo
export LIBVIRT_DEFAULT_URI="qemu:///system" edit sur VM running virsh edit ubuntu-cloud — les changements ne s'appliquent pas
Attention
virsh edit ubuntu-cloud — les changements ne s'appliquent pas
virsh shutdown ubuntu-cloud && virsh start ubuntu-cloud shutdown qui ne répond pas virsh shutdown ubuntu-cloud — rien ne se passe
Info
virsh shutdown ubuntu-cloud — rien ne se passe
virsh destroy ubuntu-cloud domifaddr ne montre pas d'IP virsh domifaddr ubuntu-cloud — table vide
Info
virsh domifaddr ubuntu-cloud — table vide
virsh net-dhcp-leases default Piège n°1 : destroy ne supprime rien
Section intitulée « Piège n°1 : destroy ne supprime rien »virsh destroy ubuntu-cloud # "Je supprime la VM"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 !Pour supprimer complètement une VM :
# D'abord, vérifier les volumes attachésvirsh domblklist ubuntu-cloud
# Suppression avec les volumes (IRRÉVERSIBLE)virsh undefine ubuntu-cloud --remove-all-storagePiège n°2 : session vs system
Section intitulée « Piège n°2 : session vs system »virsh list --all # Montre VM-Asudo virsh list --all # Montre VM-B, VM-CExplication : 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
virsh -c qemu:///system list --all # VMs systèmevirsh -c qemu:///session list --all # VMs utilisateurSolution 2 (par défaut) : configurer l’URI une fois
export LIBVIRT_DEFAULT_URI="qemu:///system"Piège n°3 : shutdown qui ne répond pas
Section intitulée « Piège n°3 : shutdown qui ne répond pas »virsh shutdown ubuntu-cloud# ... rien ne se passe, la VM reste runningCause : 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 :
- Attendre 30 secondes (le guest peut être lent)
- Vérifier que le package
acpidest installé dans la VM - En dernier recours :
virsh destroy
Logs et dépannage
Section intitulée « 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.
systemctl status virtqemud virtnetworkd virtstoraged# Problèmes de VMs (QEMU)journalctl -u virtqemud -f
# Problèmes de réseau virtueljournalctl -u virtnetworkd -f
# Problèmes de stockage/poolsjournalctl -u virtstoraged -fsystemctl status libvirtdjournalctl -u libvirtd -fFichiers 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é) |
Exercices flash (5 min)
Section intitulée « Exercices flash (5 min) »Trois micro-exercices pour valider vos acquis :
-
Lister et identifier — Trouvez toutes vos VMs et leur état.
Fenêtre de terminal virsh list --allvirsh dominfo <nom-vm>✓ Vous devez voir l’état (
running/shut off) et la RAM allouée. -
Cycle de vie — Démarrez, arrêtez proprement, redémarrez.
Fenêtre de terminal virsh start <nom-vm>virsh shutdown <nom-vm> # Attendre l'arrêtvirsh start <nom-vm>✓ La VM répond à
shutdown? Si non, vérifiezacpiddans la VM. -
Trouver l’IP — Testez les différentes sources.
Fenêtre de terminal virsh domifaddr <nom-vm> --source leasevirsh net-dhcp-leases default✓ Vous avez une IP ? Testez
ssh user@<ip>pour confirmer.
Cheatsheet complète
Section intitulée « Cheatsheet complète » 📋
Cheatsheet virsh
📝 Syntaxe :
virsh list --all Lister toutes les VMs virsh dominfo <vm> Infos complètes d'une VM virsh domstate <vm> État uniquement 🚀 Commandes types :
virsh list --all virsh dominfo ubuntu-cloud virsh shutdown ubuntu-cloud virsh console ubuntu-cloud virsh domifaddr ubuntu-cloud ⚙️ Options
virsh domifaddr <vm> | Adresse IP | virsh domifaddr ubuntu-cloud |
virsh domblklist <vm> | Disques attachés | virsh domblklist ubuntu-cloud |
virsh domiflist <vm> | Interfaces réseau | virsh domiflist ubuntu-cloud |
🔍 Filtres
virsh net-list --all | Lister les réseaux | virsh net-list --all |
virsh net-dhcp-leases <net> | Baux DHCP | virsh net-dhcp-leases default |
virsh net-info <net> | Info réseau | virsh net-info default |
virsh pool-list --all | Lister les pools | virsh pool-list --all |
virsh vol-list <pool> | Lister les volumes | virsh vol-list default |
virsh pool-info <pool> | Info pool | virsh pool-info default |
⚡ Actions
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 autostart | virsh autostart ubuntu-cloud |
virsh autostart --disable <vm> | Désactiver autostart | virsh autostart --disable ubuntu-cloud |
virsh define <fichier.xml> | Créer depuis XML | virsh define ubuntu.xml |
virsh undefine <vm> | Supprimer la définition | virsh undefine ubuntu-cloud |
Commandes de diagnostic
Section intitulée « 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 |
Commandes avancées (guides dédiés)
Section intitulée « Commandes avancées (guides dédiés) »| 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 |
À retenir
Section intitulée « À 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 |
Les 3 règles d’or :
- Toujours
--all— sinon vous ne voyez que les VMs running shutdownavantdestroy— arrêt propre d’aborddestroy≠ delete —destroyarrête,undefinesupprime la définition