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.

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.

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.