pvecm

Add the current node to an existing cluster

$ pvecm add [hostname_or_ip]

$ pvecm [[addn|addnode]] [node]

$ pvecm [[ap|apiver]]

$ pvecm [[c|create]] [clustername]

$ pvecm [[d|delnode]] [node]

$ pvecm [[n|nodes]]

$ pvecm [[s|status]]

pvecm command [options]

Common commands:
pvecm add IP-address [options]
pvecm delnode node-name [options]
pvecm status
pvecm nodes
pvecm qdevice sub-command [options]
pvecm expected count

--help, -h
    Show a help message and exit.

--version, -v
    Show version information and exit.

pvecm is the central command-line utility for managing a Proxmox VE High Availability cluster. It provides an interface to the underlying Corosync cluster engine and the Proxmox Cluster Filesystem (PMXCFS), allowing administrators to perform crucial tasks such as creating new clusters, adding or removing nodes, checking cluster status and membership, and configuring quorum devices (QDevice).

The command ensures the health and integrity of the HA cluster, which is essential for maintaining high availability of virtual machines and containers by enabling features like live migration and automatic failover in case of node failures. It is a critical tool for scaling Proxmox VE deployments and ensuring resilience against hardware outages and provides a unified interface for complex cluster operations.

• Cluster Quorum: A cluster must maintain quorum (a majority of nodes online) to operate. Loss of quorum can halt VMs/CTs on affected nodes.
• Network Stability: Highly dependent on stable, low-latency network communication between nodes. Unreliable networking can lead to split-brain scenarios or cluster instability.
• Node Removal: Removing a node (especially using delnode) requires careful planning. The node should be powered off and ideally removed from the cluster cleanly before physical removal. Forcing removal of an active node is dangerous and can cause cluster inconsistencies.
• IP Address Changes: Changing a node's IP address within an active cluster is complex and not directly supported via pvecm. It usually requires specific manual procedures.
• Backup: Always back up configuration files (e.g., /etc/pve/) before making significant cluster changes.

• pvecm add IP-address [options]: Joins a new node to an existing cluster. The IP address must be of an existing cluster member.
  Options include --force (force join, use with caution), --nodeid (assign a specific ID), --ring0_addr (specify network for primary Corosync ring), and --ring1_addr (specify network for secondary Corosync ring for redundancy).
  
• pvecm delnode node-name [options]: Removes a node from the cluster. The node should ideally be powered off and removed from the cluster cleanly before using this command. Using --force is highly discouraged on an active node.
  
• pvecm status: Displays the current cluster status, including quorum information, active nodes, and Corosync health.
  
• pvecm nodes: Lists all nodes that are members of the cluster, showing their node IDs and status.
  
• pvecm qdevice sub-command [options]: Manages a QDevice (Quorum Device).
  Common sub-commands: setup (configures a QDevice), destroy (removes QDevice configuration), status (shows QDevice status). A QDevice is crucial for maintaining quorum in two-node clusters.

In a Corosync cluster, quorum is achieved when a majority of votes are present. Each node typically contributes one vote. For a cluster to operate, more than half of the total votes must be online. This mechanism prevents split-brain scenarios where two halves of a cluster could operate independently, leading to data corruption.

For a two-node cluster (total 2 votes), a simple majority isn't possible (e.g., if one node fails, only 1 out of 2 votes remain, which is 50%, not a majority). A QDevice (Quorum Device) provides an additional third vote from an external server. If one node fails, the remaining node plus the QDevice can form a majority (2 out of 3 votes), allowing the cluster to remain active and maintain HA services.

Proxmox VE clusters require a dedicated, low-latency, and high-bandwidth network for Corosync communication. It is highly recommended to use at least two redundant network interfaces (configured as ring0 and ring1) for Corosync to ensure high availability of the cluster communication itself. These interfaces should ideally be on separate physical networks or VLANs to protect against single points of failure, ensuring robust cluster operation even during network component failures.

Proxmox VE's cluster capabilities have evolved significantly, primarily leveraging Corosync for robust inter-node communication and quorum management. pvecm emerged as the primary user-facing tool, abstracting the complexities of Corosync configuration into simplified commands. Early versions of Proxmox VE also relied on CMAN/OpenAIS before fully transitioning to Corosync. The continuous development focuses on improving cluster stability, ease of management, and integrating new features like QDevice for better quorum handling in two-node clusters.

corosync(8), pmxcfs(5), pve-ha-manager(1), pve-ha-lrm(1)