Administration CLI Proxmox VE : Diagnostic Cluster

L'administration efficace d'un cluster Proxmox VE repose sur la maîtrise des outils en ligne de commande pour le diagnostic, la maintenance et le dépannage. Ce guide CLI complet rassemble toutes les commandes essentielles pour surveiller Corosync, analyser le réseau, gérer les stockages ZFS et Ceph, piloter les sauvegardes et résoudre les problèmes courants en production. Que vous fassiez face à une perte de quorum, un pool ZFS dégradé, des VMs bloquées ou des erreurs de synchronisation Ceph, ce guide de référence vous fournit les commandes exactes à exécuter dans l'ordre, avec les explications des outputs attendus. La CLI Proxmox s'appuie sur des outils natifs Linux (systemctl, ip, ss, journalctl) complétés par les utilitaires spécifiques Proxmox (pvecm, pvesh, pvesr, qm, pct, vzdump). Maîtriser ces outils vous permet d'administrer votre cluster même sans accès à l'interface web, scénario critique lors de pannes majeures. Ce guide inclut également des procédures de récupération d'urgence pour les situations les plus complexes.

Diagnostic du Cluster et de Corosync

pvecm est l'outil principal de gestion du cluster Proxmox. Les commandes de diagnostic indispensables :

• pvecm status : état général du cluster, quorum, liste des nœuds et leur statut (online/offline)
• pvecm nodes : liste détaillée des nœuds avec leur ID, adresse IP et état
• corosync-quorumtool -s : état détaillé du quorum avec les votes de chaque nœud
• journalctl -u corosync -f : logs Corosync en temps réel (indispensable lors d'incidents)
• corosync-cfgtool -s : état des anneaux de communication Corosync (ring0, ring1)

En cas de perte de quorum sur un nœud isolé, la procédure de récupération d'urgence est : s'assurer que tous les autres nœuds sont éteints, puis exécuter pvecm expected 1 pour forcer le quorum. Cette opération est irréversible et risquée : exécutez-la uniquement si vous êtes certain que les autres nœuds sont hors ligne.

Gestion des VMs et Conteneurs en CLI

qm (QEMU Manager) et pct (Proxmox Container Toolkit) sont les outils CLI de gestion des VMs KVM et conteneurs LXC respectivement :

• qm list / pct list : liste toutes les VMs/CTs avec leur état
• qm start/stop/reset {vmid} : démarrer/arrêter/redémarrer une VM
• qm status {vmid} : état détaillé d'une VM (running, stopped, paused)
• qm unlock {vmid} : déverrouille une VM bloquée en état "locked" (utiliser avec précaution)
• qm monitor {vmid} : accès à la console QEMU monitor (pour diagnostics bas niveau)
• pct enter {ctid} : entre dans un conteneur LXC (équivalent SSH)

Pour les migrations manuelles : qm migrate {vmid} {target_node} --online (live migration) ou qm migrate {vmid} {target_node} (offline migration). Vérifier l'espace disponible sur le nœud destination avant toute migration.

Diagnostic Stockage ZFS

Les commandes ZFS essentielles pour le diagnostic en production :

• zpool status -v : état détaillé de tous les pools ZFS (dégradé, faulted, scrubbing)
• zpool list : utilisation et état de chaque pool (capacité, fragmentation)
• zfs list -t all : liste datasets et snapshots avec utilisation
• zpool scrub {pool} : lance une vérification de l'intégrité des données
• zpool iostat -v 1 : statistiques I/O en temps réel par vdev

En cas de pool DEGRADED, identifier le disque défaillant avec zpool status -v, remplacer le disque et lancer la reconstruction avec zpool replace {pool} {old_disk} {new_disk}. Surveiller la progression de la reconstruction avec zpool status -v (affiche le pourcentage resilvering). Pour l'optimisation ZFS avancée, consultez notre guide d'optimisation Proxmox VE.

Diagnostic Stockage Ceph

Ceph (Controlled Replication Under Scalable Hashing) dispose d'outils CLI puissants pour le diagnostic :

• ceph status ou ceph -s : état global du cluster Ceph (HEALTH_OK/WARN/ERR)
• ceph health detail : détail des avertissements et erreurs en cours
• ceph osd tree : arbre des OSDs avec leur état (up/down, in/out)
• ceph df : utilisation par pool et espace global disponible
• ceph osd perf : performances des OSDs (latence apply/commit)
• pveceph status : état Ceph intégré à Proxmox

En cas d'OSD défaillant (status down), diagnostiquer avec journalctl -u ceph-osd@{id}. Si l'OSD peut être relancé : systemctl start ceph-osd@{id}. Pour un remplacement de disque, marquer l'OSD out puis le supprimer : ceph osd out {id}, ceph osd rm {id}, puis ajouter le nouveau disque via pveceph.

Sauvegardes et Restaurations avec vzdump

vzdump est l'outil de sauvegarde natif Proxmox, supportant les VMs KVM et conteneurs LXC :

• vzdump {vmid} --storage {storage} --mode snapshot : sauvegarde en mode snapshot (recommandé)
• vzdump {vmid} --compress zstd --mode suspend : sauvegarde avec compression ZSTD
• qmrestore {backup_file} {vmid} --storage {storage} : restauration d'une VM
• pct restore {ctid} {backup_file} : restauration d'un conteneur LXC

Les sauvegardes planifiées sont gérées via Datacenter → Backup ou directement dans /etc/pve/jobs.cfg. Les logs de sauvegardes se trouvent dans /var/log/vzdump/. Pour une stratégie complète de sauvegarde, consultez notre guide Proxmox Backup Server.

Utilisation de pvesh pour l'Automatisation API

pvesh est l'interface CLI de l'API REST Proxmox VE, permettant d'effectuer toutes les opérations de l'interface web depuis le terminal. Exemples d'usage :

• pvesh get /nodes : liste les nœuds du cluster avec leur statut
• pvesh get /cluster/ha/resources : liste les ressources HA configurées
• pvesh create /nodes/{node}/qemu/{vmid}/status/start : démarre une VM via API
• pvesh get /cluster/log --max 50 : affiche les 50 derniers événements cluster

pvesh est particulièrement utile pour les scripts d'administration et l'intégration avec des outils d'automatisation. Les API tokens (générés dans Datacenter → Permissions → API Tokens) permettent d'authentifier les scripts sans exposer le mot de passe. La documentation complète des endpoints est accessible sur la visionneuse API Proxmox. Pour le déploiement automatisé avancé, consultez notre guide Terraform et Ansible pour Proxmox. Référencez également le forum Proxmox pour les cas d'usage avancés.

Administration du stockage Ceph en CLI

Proxmox VE intègre un client Ceph complet accessible directement depuis chaque nœud du cluster. Au-delà des commandes de diagnostic de base, la gestion opérationnelle de Ceph en production nécessite la maîtrise des commandes de gestion des OSD, des pools et des flags de maintenance. Ces opérations sont indispensables lors des maintenances nœud, des remplacements de disques ou des incidents de santé Ceph.

Commandes de santé et de supervision globale

# État complet du cluster Ceph (sortie formatée)
ceph status
ceph -s

# Détail exhaustif des alertes et erreurs en cours
ceph health detail

# Surveillance continue de l'état (actualisation toutes les 5 secondes)
watch -n 5 ceph status

# Statistiques d'utilisation globale et par pool
ceph df

# Performances des OSDs (latence apply/commit en ms)
ceph osd perf

# Débits I/O en temps réel (Proxmox VE)
pveceph status

Gestion des OSD (Object Storage Daemons)

# Arbre des OSDs avec états et emplacements physiques
ceph osd tree

# Liste des OSDs avec leurs états (up/down, in/out)
ceph osd dump | grep -E "^osd\."

# Voir les statistiques d'un OSD spécifique
ceph osd find 0
ceph tell osd.0 version

# Diagnostiquer un OSD défaillant (logs systemd)
journalctl -u ceph-osd@0 --since "1 hour ago"

# Redémarrer un OSD défaillant
systemctl restart ceph-osd@0

# Marquer un OSD comme "out" avant remplacement (déclenche le rebalancing)
ceph osd out 0

# Arrêter le service OSD avant maintenance disque
systemctl stop ceph-osd@0

# Supprimer un OSD de la CRUSH map (après remplacement)
ceph osd crush remove osd.0
ceph auth del osd.0
ceph osd rm 0

# Ajouter un nouveau disque OSD via Proxmox
pveceph osd create /dev/sdb

Gestion des pools Ceph

# Lister tous les pools et leurs paramètres
ceph osd pool ls detail

# Statistiques détaillées par pool
ceph osd pool stats

# Utilisation par pool (objets, données, ratio)
rados df

# Créer un pool repliqué (3 réplicas recommandé en production)
ceph osd pool create vm-pool 128 128 replicated

# Modifier le nombre de réplicas d'un pool
ceph osd pool set vm-pool size 3
ceph osd pool set vm-pool min_size 2

# Supprimer un pool (irréversible — nécessite confirmation double)
ceph osd pool delete vm-pool vm-pool --yes-i-really-really-mean-it

Flags de maintenance Ceph

Les flags Ceph permettent de contrôler le comportement du cluster pendant les maintenances. Leur utilisation correcte est critique pour éviter une charge excessive lors des arrêts planifiés de nœuds.

# Désactiver le rebalancing (OBLIGATOIRE avant arrêt d'un nœud en maintenance)
ceph osd set noout
ceph osd set norebalance

# Désactiver la récupération (recovery) pour ne pas saturer le réseau
ceph osd set norecover

# Vérifier les flags actifs
ceph osd dump | grep flags

# Réactiver après fin de maintenance (OBLIGATOIRE après redémarrage du nœud)
ceph osd unset noout
ceph osd unset norebalance
ceph osd unset norecover

# Désactiver temporairement les alertes HEALTH_WARN (scrub en retard, etc.)
ceph osd set noscrub
ceph osd set nodeep-scrub

Sauvegarde et restauration avec PBS en CLI

Proxmox Backup Server (PBS) est la solution de sauvegarde dédiée à l'écosystème Proxmox. Contrairement à vzdump qui génère des archives monolithiques, PBS utilise un mécanisme de déduplication par chunks qui rend les sauvegardes incrémentielles très efficaces. L'intégration PBS dans Proxmox VE permet d'interagir avec le datastore depuis la CLI du nœud hyperviseur.

Configuration et accès au stockage PBS

# Lister les stockages configurés (PBS apparaît en type pbs)
pvesm status

# Détail d'un stockage PBS spécifique
pvesm list pbs-store

# Contenu du datastore PBS (liste des sauvegardes disponibles)
pvesm list pbs-store --content backup

# Vérifier la connexion au serveur PBS
pvesh get /storage/pbs-store/status

Lancer des sauvegardes PBS depuis la CLI

# Sauvegarde d'une VM vers le stockage PBS (mode snapshot recommandé)
vzdump 101 --storage pbs-store --mode snapshot

# Sauvegarde avec compression zstd (meilleur ratio vitesse/taille)
vzdump 101 --storage pbs-store --mode snapshot --compress zstd

# Sauvegarde de plusieurs VMs en parallèle
vzdump 101 102 103 --storage pbs-store --mode snapshot --maxfiles 7

# Sauvegarde de toutes les VMs du nœud local
vzdump --all --storage pbs-store --mode snapshot

# Suivre la progression d'une sauvegarde en cours
journalctl -u vzdump -f

Restauration depuis PBS

# Lister les sauvegardes disponibles pour une VM
pvesm list pbs-store --content backup | grep "vm/101"

# Restaurer une VM depuis PBS (avec écrasement si elle existe)
qmrestore pbs-store:backup/vm/101/2026-05-29T03:00:00Z 101 --storage local-zfs

# Restaurer vers un nouvel ID de VM
qmrestore pbs-store:backup/vm/101/2026-05-29T03:00:00Z 201 --storage local-zfs

# Restaurer un conteneur LXC depuis PBS
pct restore 102 pbs-store:backup/ct/102/2026-05-29T03:00:00Z --storage local-zfs

# Vérification de l'intégrité d'une sauvegarde PBS (depuis le serveur PBS)
proxmox-backup-client snapshot verify vm/101/2026-05-29T03:00:00Z --repository user@pbs-server:datastore

Gestion des snapshots et rétention PBS

# Supprimer une sauvegarde spécifique depuis le nœud PVE
pvesm remove pbs-store:backup/vm/101/2026-05-20T03:00:00Z

# Vérifier les jobs de sauvegarde planifiés
cat /etc/pve/jobs.cfg

# Forcer l'exécution immédiate d'un job de sauvegarde planifié
pvesh create /nodes/$(hostname)/vzdump --vmid 101 --storage pbs-store --mode snapshot

# Logs des sauvegardes récentes
ls -lt /var/log/vzdump/
tail -100 /var/log/vzdump/vzdump-qemu-101-*.log 2>/dev/null || journalctl -u vzdump --since "24 hours ago"

Procédure d'arrêt ordonné d'un cluster Proxmox

L'arrêt non ordonné d'un cluster Proxmox (coupure d'alimentation, arrêt brutal des nœuds) peut engendrer des incohérences Ceph, des pertes de quorum Corosync et des VMs bloquées en état inconsistant. La procédure d'arrêt ordonné ci-dessous doit être suivie scrupuleusement lors des maintenances planifiées, des déménagements de datacenter ou des mises à jour matérielles majeures.

Phase 1 : Préparer l'arrêt (sur chaque nœud, depuis le nœud primaire)

# Vérifier l'état initial du cluster et de Ceph
pvecm status
ceph status

# Identifier toutes les VMs en cours d'exécution
qm list | grep running
pct list | grep running

# Désactiver les jobs de sauvegarde planifiés pour éviter des déclenchements intempestifs
systemctl stop pvescheduler

Phase 2 : Arrêt ordonné des VMs et conteneurs

# Arrêter proprement toutes les VMs (attendre l'arrêt complet de chacune)
for vmid in $(qm list | awk 'NR>1 && $3=="running" {print $1}'); do
    echo "Arrêt VM $vmid..."
    qm shutdown $vmid
done

# Attendre que toutes les VMs soient arrêtées
watch -n 2 "qm list | grep running"

# Arrêter les conteneurs LXC
for ctid in $(pct list | awk 'NR>1 && $2=="running" {print $1}'); do
    echo "Arrêt CT $ctid..."
    pct shutdown $ctid
done

Phase 3 : Désactivation de HA et mise en maintenance Ceph

# Désactiver le gestionnaire HA pour éviter des redémarrages non désirés
ha-manager crm-command disable

# Positionner les flags Ceph AVANT d'arrêter les OSD
# (évite un rebalancing massif inutile pendant l'arrêt)
ceph osd set noout
ceph osd set norebalance
ceph osd set norecover
ceph osd set noscrub
ceph osd set nodeep-scrub

# Vérifier que les flags sont bien positionnés
ceph osd dump | grep flags

Phase 4 : Arrêt des services Proxmox et Ceph (nœud par nœud)

# Sur chaque nœud NON primaire d'abord, puis le primaire en dernier :

# Arrêter les OSD Ceph sur le nœud local
systemctl stop ceph-osd.target

# Arrêter le MDS Ceph (si CephFS activé)
systemctl stop ceph-mds.target

# Arrêter le MON Ceph sur le nœud local
systemctl stop ceph-mon.target

# Arrêter les services Proxmox
systemctl stop pve-ha-lrm pve-ha-crm
systemctl stop pvestatd pvescheduler
systemctl stop corosync

# Éteindre le nœud proprement
shutdown -h now

Phase 5 : Redémarrage ordonné après maintenance

# Démarrer les nœuds un par un, en commençant par le primaire (quorum holder)
# Attendre que chaque nœud rejoigne le cluster avant de démarrer le suivant

# Vérifier le quorum après chaque démarrage
pvecm status

# Vérifier l'état Ceph (attendre HEALTH_OK avant de continuer)
watch -n 5 ceph status

# Retirer les flags de maintenance Ceph (OBLIGATOIRE)
ceph osd unset noout
ceph osd unset norebalance
ceph osd unset norecover
ceph osd unset noscrub
ceph osd unset nodeep-scrub

# Réactiver le gestionnaire HA
ha-manager crm-command enable

# Redémarrer les VMs critiques
ha-manager status
qm start 101

Questions fréquentes

Comment récupérer un cluster Proxmox ayant perdu le quorum ?

La perte de quorum bloque toutes les opérations sur les nœuds affectés. Pour récupérer, la procédure dépend du scénario : si c'est un problème réseau temporaire, rétablir la connectivité suffit. Si un nœud est définitivement hors service, sur le nœud survivant, exécuter pvecm expected 1 après s'être assuré que le nœud défaillant est physiquement éteint (pour éviter le split-brain). Cette opération force le quorum à 1 vote disponible. Après récupération, vérifier l'état avec pvecm status et relancer les VMs protégées par HA si nécessaire.

Comment diagnostiquer une VM bloquée en état "locked" dans Proxmox VE ?

Une VM en état "locked" est généralement le résultat d'une opération interrompue (sauvegarde, migration, snapshot). Pour diagnostiquer, consulter les logs dans /var/log/pve/tasks/ en cherchant la tâche correspondante. La commande qm config {vmid} affiche le type de verrou actif (backup, migrate, snapshot, rollback). Pour déverrouiller : qm unlock {vmid}. Utiliser cette commande avec précaution : elle ignore l'état interne de l'opération interrompue et peut laisser des snapshots orphelins qu'il faut nettoyer manuellement avec qm delsnapshot {vmid} {snapname}.

Quelles sont les premières commandes à exécuter lors d'un incident cluster Proxmox ?

La procédure de triage recommandée : 1) pvecm status pour évaluer l'état du quorum et identifier les nœuds offline. 2) journalctl -u corosync --since "30 min ago" pour identifier les événements récents ayant déclenché l'incident. 3) zpool status -v et ceph status pour vérifier l'état du stockage. 4) qm list pour voir les VMs et leur état sur le nœud local. Cette séquence permet de catégoriser rapidement l'incident (réseau, stockage, nœud) et d'appliquer la procédure de récupération appropriée.

Sources et références : Proxmox VE Wiki · ANSSI

Conclusion

La maîtrise de la CLI Proxmox VE est une compétence fondamentale pour tout administrateur d'infrastructure virtualisée. pvecm, qm, pct, pvesh, vzdump, zpool et ceph forment la boîte à outils complète pour diagnostiquer, maintenir et récupérer un cluster Proxmox dans toutes les situations, y compris les plus critiques où l'interface web est inaccessible.

Sécurisez votre infrastructure virtualisée

Audit Proxmox, VMware, Hyper-V — durcissement hyperviseur, segmentation, protection anti-ransomware.

Demander un audit [email protected]