Proxmox VE : guide pratique de dépannage avec commandes copiables-collables

Lorsque Proxmox VE tombe en panne, la différence entre une réparation de cinq minutes et une interruption de quatre heures tient à l'existence d'un processus reproductible. Ce guide fournit un flux de travail structuré — inventaire, pratiques de modification sûres, diagnostics ciblés et récupération étape par étape — pour les défaillances les plus courantes. Chaque commande est testée, copiable-collable, et inclut la sortie attendue afin que vous puissiez vérifier avant de passer à l'étape suivante.

Public visé : ingénieurs DevOps, équipes plateforme et fondateurs techniques exploitant des nœuds ou clusters Proxmox qui ont besoin de schémas de dépannage fiables et à faible risque.

Périmètre : services principaux (pveproxy, pvedaemon, pve-cluster, corosync), machines virtuelles QEMU (qm), conteneurs LXC (pct), stockage (LVM-thin, ZFS, Ceph RBD) et réseau par ponts Linux.

Prérequis : Proxmox VE basé sur Debian, accès console (physique, IPMI/iKVM ou console hyperviseur) et au moins une sauvegarde ou un instantané récent des invités critiques.

---

1. Inventaire des versions et de l'environnement

Avant toute modification, capturez un instantané complet de l'environnement. Cela garantit que vos diagnostics correspondent à ce qui tourne réellement et vous donne une base de référence pour un retour arrière éventuel.

Prérequis

• Accès console au cas où la connectivité réseau serait perdue.
• Fenêtre de maintenance pour les étapes disruptives (redémarrages de services, réparations de stockage).
• Sauvegardes actuelles des invités critiques ou instantanés le cas échéant.

Commandes d'inventaire en lecture seule

Versions système et Proxmox

pveversion -v
uname -r
cat /etc/debian_version

État du cluster et du quorum (si cluster)

pvecm status
pvecm nodes
systemctl status corosync
journalctl -u corosync --since "-1h"

Services principaux

systemctl status pveproxy pvedaemon pve-cluster
journalctl -u pveproxy -u pvedaemon -u pve-cluster --since "-1h"

Aperçu réseau

ip -br a
ip -br link
cat /etc/network/interfaces
ss -tulpn | grep 8006   # Interface web (HTTPS)

Inventaire stockage

pvesm status
lvs -a -o+seg_monitor
vgs
df -hT | sort -k6
zpool status   # si ZFS est utilisé

Machines virtuelles et conteneurs

qm list
pct list

Ceph optionnel (si configuré sur le nœud)

ceph -s
ceph health detail

Ce qu'il faut consigner

• Version Proxmox et noyau.
• Rôle du nœud (autonome, membre de cluster), état du quorum et nombre de nœuds en ligne.
• Ponts (vmbrX) et correspondance des cartes physiques.
• Type de stockage par invité (LVM-thin, ZFS, Ceph RBD, NFS, etc.).
• Services dégradés ou en échec.

Tableau de triage rapide

---

2. Chemin de configuration sécurisé

L'objectif est d'apporter le plus petit changement qui valide ou invalide une hypothèse tout en gardant une voie de retour ouverte.

Principes

• Privilégier d'abord les commandes en lecture seule ; n'apporter de modifications qu'après avoir confirmé une cause probable.
• Protéger l'accès : effectuer les modifications réseau disruptives depuis la console locale ; tester avec ifupdown2 quand c'est possible.
• Éviter les redémarrages à l'échelle du cluster ; corriger le plus petit composant défaillant.
• Observer les verrous et les tâches en cours avant de forcer des déverrouillages.

Garde-fous pratiques

• Conserver un shell fonctionnel avant d'appliquer des changements réseau ou stockage : garder une session SSH root et une session console ouvertes. Si SSH coupe, la console reste disponible.
• Si le nœud fait partie d'un cluster, ne redémarrer le service que sur le nœud affecté, sauf si vous traitez un problème à l'échelle du cluster.
• Avant de déverrouiller un invité, confirmer qu'aucune tâche de sauvegarde ou réplication n'est encore en cours.

Commandes couramment sûres vs modifiantes

Changements réseau sûrs avec ifupdown2

Proxmox VE inclut ifupdown2, qui permet d'appliquer et valider les changements d'interfaces avec moins de risques :

ifquery --list
ifquery --state
ifreload -a

Testez toujours avec ifreload -a depuis la console, jamais depuis SSH, quand vous modifiez la configuration d'un pont ou d'une carte physique.

---

3. Vérification et diagnostics

Utilisez ces vérifications ciblées pour confirmer rapidement et sans risque les causes racines les plus probables.

3.1 Interface web ne répond pas (port 8006)

systemctl status pveproxy
ss -tlnp | grep 8006
curl -k https://127.0.0.1:8006

Attendu : pveproxy actif, port 8006 en écoute sur 0.0.0.0 ou ::, et curl retourne du HTML.

Si pas en écoute, inspectez les journaux récents :

journalctl -u pveproxy --since "-15m"

Constatations fréquentes : problèmes de certificat, disque plein sur la racine ou /var/log, ou conflit de port avec un autre service.

Vérifiez l'espace disque sur la racine et les partitions de journaux :

df -hT | sort -k6
journalctl -p err --since "-1h"

3.2 VM qui ne démarre pas (exemple VMID 101)

qm status 101
qm config 101
ls -l /etc/pve/qemu-server/101.conf

Vérifiez un état verrouillé :

qm list | grep 101   # affiche lock=backup ou lock=snapshot si présent

Vérifiez l'utilisation du stockage et du thinpool :

lvs -a -o+data_percent,metadata_percent
pvesm status

Si les journaux mentionnent des erreurs d'I/O ou image introuvable, inspectez syslog et journaux qemu :

journalctl -xe --since "-15m" | grep -i -E "qemu|kvm|storage|i/o|ioerror"

Attendu : une raison de verrou claire, espace insuffisant, chemin de disque manquant ou erreur de permission.

3.3 Cluster sans quorum (exemple : cluster 3 nœuds, seul 1 nœud up)

pvecm status
systemctl status corosync
journalctl -u corosync --since "-30m"

Vérifiez la synchronisation horaire et la joignabilité réseau sur l'interface d'anneau corosync (généralement ring0) :

timedatectl
ping -c3 <ip-pair-ring0>

Attendu : corosync non sain, nombre de nœuds inférieur à l'attendu, partition réseau possible ou dérive temporelle > 50 ms.

3.4 Sauvegardes lentes ou en échec

ls -1 /var/log/vzdump/
tail -n 200 /var/log/vzdump/*

Vérifiez la pression I/O et la latence du stockage :

iostat -xz 5 3
pvesm status

Attendu : saturation du stockage réseau, thinpool près de la limite, ou CPU lié à la compression (gzip mono-thread sur grosses VMs).

---

4. Modes de défaillance et récupération

Corrections étape par étape avec notes de retour arrière et vérifications.

A) Interface web indisponible suite à une défaillance pveproxy

1. Vérifiez et capturez les journaux :

   systemctl status pveproxy
   journalctl -u pveproxy --since "-30m"

1. Si l'espace disque est faible, libérez de l'espace (voir section D). Si le port 8006 est occupé par un autre service, arrêtez le service conflictuel.
2. Redémarrez pveproxy proprement :

   systemctl restart pveproxy

1. Vérifiez :

   ss -tlnp | grep 8006
   curl -k https://127.0.0.1:8006

Retour arrière : si le redémarrage cause des problèmes plus larges, revenez en redémarrant seulement pveproxy vers un état connu bon, ou redémarrez le nœud pendant une fenêtre de maintenance si les dépendances de services sont emmêlées.

---

B) VM bloquée avec verrou ou qui ne démarre pas

1. Confirmez qu'aucune sauvegarde n'est en cours pour cette VM :

   ps aux | grep vzdump | grep 101 || true

1. Si un verrou obsolète est présent et qu'aucune tâche ne tourne, levez-le :

   qm unlock 101

1. Revérifiez la configuration et démarrez :

   qm config 101
   qm start 101

Vérification : qm status 101 affiche running ; la console se connecte.

Retour arrière : ne supprimez ni ne déplacez les images disque. Si vous avez modifié la configuration, gardez une sauvegarde de /etc/pve/qemu-server/101.conf avant les modifications et restaurez-la si la VM ne démarre pas après les changements.

1. Si le stockage est plein ou les métadonnées du thinpool à 100 %, corrigez le stockage d'abord (voir section D).

---

C) Pas de quorum dans un cluster

Préconditions : comprendre que démarrer des VMs gérées par HA sans quorum risque le split-brain. Travaillez depuis la console si le réseau est instable.

1. Identifiez quels nœuds sont up :

   pvecm nodes
   pvecm status

1. Corrigez la joignabilité réseau sur les interfaces d'anneau corosync (souvent ring0). Vérifiez le lien up et l'accessibilité IP vers les pairs. Corrigez d'abord le câblage, les VLAN ou les problèmes de pont.
2. Vérifiez que l'heure est saine et synchronisée :

   timedatectl

1. Redémarrez corosync sur les nœuds affectés seulement après que le réseau est stable :

   systemctl restart corosync

1. Vérifiez :

   pvecm status   # cherchez Quorate: Yes et le nombre de nœuds attendu

Retour arrière : si le quorum ne peut être rétabli rapidement, il peut être plus sûr de maintenir la partition minoritaire éteinte (ou les services HA arrêtés) jusqu'au retour de la connectivité. Évitez de forcer les services sans quorum sauf si vous isolez complètement l'autre partition.

---

D) Disque plein : système de fichiers racine ou thinpool

Système de fichiers racine plein

1. Identifiez l'utilisation de l'espace :

   df -hT
   journalctl -p err --since "-1h"

1. Nettoyez les coupables courants prudemment :

   apt-get clean
   journalctl --vacuum-time=7d
   rm -f /var/lib/vz/template/iso/*.iso   # seulement si sûr de supprimer
   find /var/log -type f -name "*.log" -size +200M -print

1. Vérifiez les fichiers supprimés-ouverts (espace non libéré) :

   lsof +L1 | head -n 20

1. Vérifiez l'espace libre :

   df -hT

Retour arrière : si un nettoyage a supprimé des artefacts nécessaires, restaurez-les depuis la sauvegarde ou recréez-les au besoin (par exemple, images ISO).

LVM-thin presque ou totalement utilisé (exemple thinpool : pve/data)

1. Inspectez l'utilisation :

   lvs -a -o+data_percent,metadata_percent pve/data

1. Si les données sont près de 100 %, étendez le thinpool (assurez-vous qu'il y a de l'espace libre dans le VG) :

   lvextend -L +20G pve/data

1. Si les métadonnées sont hautes (par exemple >85 %) ou pleines, étendez les métadonnées prudemment :

   lvextend --poolmetadatasize +1G pve/data

1. Revérifiez :

   lvs -a -o+data_percent,metadata_percent pve/data

Retour arrière : si vous avez sur-étendu, vous pouvez réduire d'autres LV ou ajouter un nouveau PV et vgextend le VG, mais réduire les thinpools est risqué ; préférez ajouter de la capacité plutôt que d'inverser les changements thin.

1. Démarrez/relancez la VM affectée.

Pool ZFS dégradé

1. Inspectez le pool :

   zpool status

1. Identifiez le périphérique défaillant et mappez-le à un disque physique par numéro de série :

   ls -l /dev/disk/by-id/

1. Remplacez ou rattachez (exemple) :

   zpool replace rpool /dev/disk/by-id/old-disk-id /dev/disk/by-id/new-disk-id

1. Surveillez la resynchronisation :

   zpool status

Retour arrière : si le mauvais disque a été détaché, remettez-le en ligne rapidement :

zpool online rpool /dev/disk/by-id/that-disk

---

E) Changement réseau vous ayant verrouillé dehors

1. Utilisez la console pour vous connecter.
2. Restaurez le fichier interfaces précédent connu bon :

   cp /etc/network/interfaces.bak /etc/network/interfaces
   ifreload -a   # ifupdown2

1. Si ifreload échoue, utilisez ifdown/ifup sur l'interface/pont spécifique :

   ifdown vmbr0 && ifup vmbr0

1. Validez le lien et l'adresse :

   ip -br a
   ping -c3 passerelle-par-defaut

Retour arrière : gardez une sauvegarde datée de /etc/network/interfaces avant chaque changement. Si le pont a perdu sa carte esclave, assurez-vous que la stanza de la carte physique est manual et esclave de vmbr0, pas configurée avec une IP.

---

F) Configuration VM corrompue ou manquante

1. Vérifiez si la configuration existe :

   ls -l /etc/pve/qemu-server/

1. Si manquante mais que les images disque existent sur le stockage, recréez une configuration minimale et rattachez les disques (exemple VMID 101, chemin disque local-lvm:vm-101-disk-0) :

   qm create 101 --name recovered-101 --memory 4096 --cores 2 --net0 virtio,bridge=vmbr0
   qm set 101 --scsi0 local-lvm:vm-101-disk-0
   qm set 101 --boot order=scsi0
   qm start 101

Retour arrière : sauvegardez la configuration recréée avant d'autres changements pour pouvoir revenir à la base minimale fonctionnelle si nécessaire.

1. Si une ancienne sauvegarde de configuration existe, restaurez-la, puis vérifiez que le matériel correspond aux disques attachés.

---

G) Sauvegardes en échec ou trop lentes

1. Inspectez les journaux vzdump et les tâches récentes :

   tail -n 200 /var/log/vzdump/*
   cat /var/log/pve/tasks/index

1. Vérifiez la latence et l'espace du stockage cible :

   pvesm status

1. Corrections de triage :

• Déplacez la fenêtre de sauvegarde vers des périodes de moindre I/O.
• Si stockage réseau, vérifiez MTU et chemin (pas d'asymétrie), et testez avec une copie de fichier simple.
• Réduisez la compression ou activez pigz si CPU bound :

     # Dans /etc/vzdump.conf ou par job :
     pigz: 1

Retour arrière : annulez tout changement de compression ou planification s'ils causent une charge plus élevée ailleurs.

1. Vérifiez : lancez une sauvegarde d'une petite VM unique pour confirmer les améliorations.

---

5. Liste de contrôle opérationnelle

Utilisez ceci comme routine rapide avant et pendant les incidents.

Santé quotidienne/hebdomadaire

• pveversion -v et apt list --upgradable pendant les fenêtres de maintenance seulement.
• pvecm status affiche Quorate: Yes dans les clusters.
• df -hT, lvs -a et zpool status montrent une marge saine (cible >20 % libre).
• journalctl -p err --since "yesterday" est vide ou attendu.
• pvesm status affiche OK pour tous les stockages.

Avant d'apporter des changements

• Prenez ou confirmez une sauvegarde/instantané récent des invités critiques.
• Sauvegardez /etc/network/interfaces vers /etc/network/interfaces.bak.
• Gardez une session console ouverte en cas de perte SSH.
• Planifiez un retour arrière : connaissez la commande pour annuler le dernier changement.

Pendant le triage d'incident

• Identifiez un symptôme principal unique et lancez les deux premières vérifications en lecture seule.
• Formez une hypothèse étroite ; testez avec le plus petit changement sûr.
• Après chaque changement, vérifiez l'amélioration ou revenez immédiatement.

Vérification post-correction

• Confirmez les services : systemctl status pveproxy pvedaemon pve-cluster.
• Confirmez l'état des invités : qm list, pct list.
• Confirmez la santé stockage et réseau.
• Documentez cause, correction et garde-fou pour prévenir la récurrence.

Déclencheurs et actions de retour arrière

---

Conclusion

Dépanner Proxmox VE de façon fiable est une question de discipline : rassembler d'abord les versions et la topologie, privilégier les vérifications en lecture seule, changer une chose à la fois, et toujours garder une voie de retour claire. Avec les inventaires, ensembles de commandes sûrs, étapes de vérification et flux de récupération de ce guide, vous pouvez gérer les défaillances les plus courantes rapidement et en confiance. Commencez par la correction la plus petite et plausible, vérifiez le résultat attendu, et documentez l'apprentissage. Au fil du temps, ces schémas réduisent la durée des incidents et rendent vos opérations Proxmox plus prévisibles.