Aller au contenu
English
English
Virtualisation medium

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

60 min de lecture

Logo 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.

Le tableau regroupe les commandes par intention plutôt que par ordre alphabétique : vous partez de ce que vous voulez obtenir, et vous lisez la commande correspondante. Les lignes « Voir » et « Diagnostiquer » sont des opérations en lecture seule, sans risque sur un hôte inconnu ; « Contrôler » et « Configurer » modifient la machine et demandent de savoir ce qu'on fait.

CompétenceCommandes clés
Voir l'état des VMslist, dominfo, domstate
Contrôler le cycle de viestart, shutdown, destroy, reboot
Diagnostiquer une VMdomifaddr, domblklist, domiflist
Configurer une VMedit, dumpxml, autostart
Gérer réseau et stockagenet-*, pool-*, vol-*

Ce guide suppose que vous avez :

🧠 Modèle mental : Comment fonctionne virsh

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

Modèle mental virsh : Commande (list, start, dominfo) → Cible (domain=VM, network, pool) → Résultat (état, config, action)

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

Le schéma suivant montre le chemin réel d'une commande, du terminal jusqu'au processus QEMU qui porte la machine virtuelle.

Architecture virsh : commandes CLI vers démons libvirt, processus QEMU puis module KVM

Les messages de virsh n'emploient jamais le mot « VM » : ils parlent de domain, de pool et de volume. Ce tableau fait la traduction dans les deux sens, et il sert surtout à lire les erreurs : failed to get domain veut dire « je ne trouve pas cette machine », pas « le domaine DNS est injoignable ». La colonne d'état est tout aussi importante, car shut off et paused décrivent deux situations sans rapport.

Terme libvirtSignificationÉquivalent courant
domainMachine virtuelleVM
poolConteneur de stockageDossier ou LV
volumeDisque dans un poolFichier qcow2
networkRéseau virtuelBridge ou NAT
runningVM en coursAllumée
shut offVM arrêtéeÉteinte
pausedVM suspendueGelée en RAM

Ces huit patterns couvrent les opérations virsh du quotidien, de la simple consultation d'état à la modification de configuration. Chacun est détaillé avec sa commande exacte, un exemple de sortie commenté et les pièges qui lui sont propres.

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 :

ColonneSignification
IdNuméro d'instance (uniquement si running)
NameNom de la VM (utilisé dans toutes les commandes)
Staterunning, shut off, paused, crashed...

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 :

ChampSignification
IdNuméro d'instance (- si arrêtée)
StateÉtat actuel
CPU(s)Nombre de vCPU
Max memoryRAM allouée (en KiB)
Persistentyes = VM définie, no = transient
AutostartDémarre au boot de l'hôte

Les 4 commandes pour contrôler une VM :

Fenêtre de terminal
virsh start ubuntu-cloud
Domain 'ubuntu-cloud' started

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

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

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).

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

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

Pour diagnostiquer ou vérifier la configuration :

Fenêtre de terminal
virsh domblklist ubuntu-cloud
Target Source
-------------------------------------------------
vda /var/lib/libvirt/images/ubuntu-cloud.qcow2
sda /var/lib/libvirt/images/seed.iso

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

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.

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.

Ces six erreurs reviennent constamment chez les débutants comme chez les administrateurs pressés. Trois d'entre elles portent sur du vocabulaire trompeur (destroy, undefine, edit), deux sur un affichage incomplet (list sans --all, domifaddr sans source), la dernière sur un signal ACPI que la VM ignore. Les connaître évite des pertes de données et des heures de diagnostic.

Ce que beaucoup croient (faux)
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

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
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"
Fenêtre de terminal
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
Fenêtre de terminal
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.

Fenêtre de terminal
virsh list --all
Fenêtre de terminal
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.

Fenêtre de terminal
virsh net-dhcp-leases default
Fenêtre de terminal
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.

Fenêtre de terminal
virsh shutdown ubuntu-cloud && virsh start ubuntu-cloud

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.

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

Fichiers de logs additionnels :

FichierContenu
/var/log/libvirt/qemu/<vm>.logLogs QEMU de chaque VM
/var/log/libvirt/libvirtd.logLog principal (si activé)

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

ErreurCause probableSolution
error: failed to connect to the hypervisorUtilisateur absent du groupe libvirt, libvirtd arrêté, ou mauvais URIAjouter l'utilisateur au groupe : sudo usermod -aG libvirt $USER, puis vérifier avec virsh list --all
error: failed to get domainMauvais 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)

Trois micro-exercices pour valider vos acquis :

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

    Fenêtre de terminal
    virsh list --all
    virsh dominfo <nom-vm>

    Attendu : vous voyez l'état (running ou shut off) et la RAM allouée.

  2. 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êt
    virsh start <nom-vm>

    Attendu : la VM répond à shutdown. Si elle reste running, vérifiez acpid dans la VM.

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

    Fenêtre de terminal
    virsh domifaddr <nom-vm> --source lease
    virsh net-dhcp-leases default

    Attendu : une adresse en 192.168.122.0/24. Confirmez avec ssh user@<ip>.

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

Ce sont les commandes en lecture seule : aucune ne modifie la VM, vous pouvez toutes les lancer sans risque pour explorer un hôte inconnu. list --all est le point d'entrée, les autres prennent en argument le nom exact qu'il affiche.

SyntaxeSignificationExemple
virsh list --allLister toutes les VMsvirsh list --all
virsh dominfo <vm>Infos complètes d'une VMvirsh dominfo ubuntu-cloud
virsh domstate <vm>État uniquementvirsh domstate ubuntu-cloud
virsh domifaddr <vm>Adresse IP de la VMvirsh domifaddr ubuntu-cloud
virsh domblklist <vm>Disques attachésvirsh domblklist ubuntu-cloud
virsh domiflist <vm>Interfaces réseauvirsh domiflist ubuntu-cloud

Ces commandes changent l'état de la VM. La distinction à ne jamais oublier oppose shutdown, qui demande poliment l'arrêt via ACPI, à destroy, qui coupe l'alimentation d'un coup. Réservez le second aux VMs bloquées, car un arrêt brutal peut corrompre le système de fichiers invité.

SyntaxeSignificationExemple
virsh start <vm>Démarrervirsh 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émarrervirsh reboot ubuntu-cloud
virsh suspend <vm>Mettre en pausevirsh suspend ubuntu-cloud
virsh resume <vm>Reprendrevirsh resume ubuntu-cloud
virsh console <vm>Console série (Ctrl+] pour sortir)virsh console ubuntu-cloud

Ces commandes agissent sur la définition XML de la VM, pas sur son exécution en cours : leurs effets n'apparaissent qu'au prochain démarrage. Le duo à retenir est dumpxml pour exporter avant de toucher quoi que ce soit, et undefine qui supprime la définition tout en conservant les disques par défaut.

SyntaxeSignificationExemple
virsh dumpxml <vm>Afficher la config XMLvirsh dumpxml ubuntu-cloud
virsh edit <vm>Éditer la configvirsh edit ubuntu-cloud
virsh autostart <vm>Activer l'autostartvirsh autostart ubuntu-cloud
virsh autostart --disable <vm>Désactiver l'autostartvirsh autostart --disable ubuntu-cloud
virsh define <fichier.xml>Créer une VM depuis un XMLvirsh define ubuntu.xml
virsh undefine <vm>Supprimer la définitionvirsh undefine ubuntu-cloud

Le préfixe indique la ressource visée : net- pour les réseaux virtuels, pool- pour les conteneurs de stockage, vol- pour les disques individuels. La commande la plus utile au quotidien reste net-dhcp-leases, qui donne l'adresse IP d'une VM même quand domifaddr échoue.

SyntaxeSignificationExemple
virsh net-list --allLister les réseauxvirsh net-list --all
virsh net-dhcp-leases <net>Baux DHCP d'un réseauvirsh net-dhcp-leases default
virsh net-info <net>Info d'un réseauvirsh net-info default
virsh pool-list --allLister les pools de stockagevirsh pool-list --all
virsh vol-list <pool>Lister les volumes d'un poolvirsh vol-list default
virsh pool-info <pool>Info d'un poolvirsh pool-info default

On sort ici des opérations courantes pour aller chercher des mesures fines. Deux de ces commandes, domtime et une partie de dommemstat, ne renvoient de valeur que si le qemu-guest-agent tourne dans la VM : sans lui, elles restent muettes ou incomplètes.

CommandeDescription
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

Ces trois commandes vivent dans le même binaire virsh que les précédentes, mais elles ne se lancent pas sur un coup de tête : chacune suppose un prérequis d'infrastructure que l'aide en ligne ne rappelle pas. Le tableau donne le risque concret encouru et la page à lire avant.

CommandeRisqueÀ lire avant
migratePerte de données si mal configuréAccès distant libvirt
snapshot-create-asIncohérence si VM non quiescéeSnapshots, clones et backups
undefine --remove-all-storageSuppression irréversibleLe piège n°1 ci-dessus

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions
6 min.
70% requis

Informations

  • Le chronomètre démarre au clic sur Démarrer
  • Questions à choix multiples, vrai/faux et réponses courtes
  • Vous pouvez naviguer entre les questions
  • Les résultats détaillés sont affichés à la fin

Lance le quiz et démarre le chronomètre

Six commandes suffisent à couvrir une journée d'exploitation : le reste du guide n'est qu'un approfondissement de ces gestes. Si vous ne devez retenir qu'une chose, retenez que le vocabulaire libvirt ne parle pas de suppression quand il dit destroy, et que virsh list ment par omission tant que vous n'ajoutez pas --all.

ConceptCommandeCe qu'elle fait
Voirlist --allToutes les VMs
InfodominfoSynthèse d'une VM
IPdomifaddr --source leaseAdresse réseau (ou agent)
DémarrerstartAllumer
ArrêtershutdownÉteindre (propre)
SauvegarderdumpxmlExporter la config

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

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.

Ce site vous est utile ?

Sachez que moins de 1% des lecteurs soutiennent ce site.

Je maintiens ce site gratuitement, sans publicité, sans profilage et sans compte à créer. Un soutien, même symbolique, m'aide à couvrir l'hébergement et à garder ces ressources gratuites. Merci pour votre appui.

Le formulaire ne s'affiche pas ? Ouvrir Ko-fi dans un onglet.

Abonnez-vous et suivez mon actualité DevSecOps sur LinkedIn