How To Connect Two Proxmox Servers: Step-by-Step Clustering Guide

To connect two Proxmox VE servers into a highly functional cluster, you must leverage the built-in Corosync cluster engine to synchronize configurations via the Proxmox Cluster File System (pmxcfs). Achieving a stable multi-node environment requires a dedicated network link with latency strictly under 2 milliseconds, identical Proxmox software versions, and proper node quorum configuration. Utilizing this guide will allow you to consolidate two distinct host interfaces into a unified management plane with seamless migration capabilities.

Pre-Clustering Requirements and Network Architecture Design

Before connecting two Proxmox VE (Virtual Environment) hosts, you must understand the underlying operational architecture. Proxmox clusters utilize Corosync to transmit cluster state, membership, and quorum voting messages. A major technical caveat of a two-node cluster is the quorum rule. In a standard cluster, a majority of nodes (greater than 50 percent) must be online to make decisions. With only two nodes, if one host goes offline, the remaining host has exactly 50 percent of the vote, losing quorum and locking the cluster filesystem.

To mitigate this split-brain risk in a two-node configuration, it is highly recommended to plan for a lightweight third-party quorum device, known as a QDevice, which acts as a tie-breaker. Furthermore, running a cluster requires precise time synchronization across both systems to prevent certificate errors and state mismatch issues.

Essential Pre-Operations Checklist

• Server Hardware and Software: Two physical servers, both running matching versions of Proxmox VE (e.g., both on Proxmox VE 8.x). Mismatched major versions are not supported for production environments.
• Networking Hardware: Minimum of two physical gigabit network interface cards (NICs) per server. One interface should be dedicated to standard virtual machine bridge traffic and management, while the second interface is dedicated to low-latency Corosync ring communication.
• IP Allocation & Hostnames: Static IP addresses assigned to both hosts. Dynamic IP addresses (DHCP) are strictly prohibited for cluster nodes. Hostnames must be unique; you cannot cluster two hosts named pve-node-01.
• Prerequisite Knowledge: Working knowledge of the Linux command line, secure shell (SSH) access parameters, and IP routing.
• Estimated Budget: $0 (utilizing existing hardware and open-source Proxmox VE software).
• Estimated Duration: 20 to 30 minutes of active configuration time.

Step-by-Step Cluster Implementation and Node Association

Step 1: Establish Network Consistency and Hostname Resolution

Before initiating any cluster software, you must ensure both nodes can reliably resolve each other's hostnames and communicate over secure ports.

First, access the command-line interface of your first Proxmox node via the web console or SSH. Open the network hosts file located at /etc/hosts using a text editor such as nano. Update this file on both servers to explicitly map the IP addresses and hostnames of both systems.

For instance, on Node One, you must add a line indicating the IP address of Node Two followed by its exact hostname. On Node Two, you must add a line representing the IP address of Node One and its corresponding hostname. Save the changes on both nodes.

Next, test connectivity between the servers. Perform a ping command from Node One to Node Two using the hostname instead of the IP address. Verify that the response times are consistent and well under the required 2-millisecond threshold. If latency spikes or packets are dropped, replace the physical network cables or troubleshoot your switch configurations before proceeding.

Step 2: Initialize the Cluster on the Primary Node

You must designate one of your Proxmox servers as the initial cluster creator. This node will host the primary configuration profile that the secondary node will clone.

Log in to the Proxmox VE Web UI of Node One by navigating to its IP address on port 8006 over HTTPS. On the left-hand navigation pane, select Datacenter. In the sub-menu that appears, click on Cluster, and then click the Create Cluster button located at the top of the interface.

A dialog window will appear requesting a Cluster Name. Enter a concise, alphanumeric name containing no spaces or special characters (for example: Production-Cluster).

Next, configure the Cluster Network. Under Link 0, select the specific network interface and subnet that you designated for internal Corosync communication. If you have a secondary physical network link for backup redundancy, you can click Add to configure Link 1 on an alternate subnet. Click Create to initialize the configuration. The system will now generate the necessary security certificates and start the Corosync service.

Pro-Tip: Always dedicate a separate physical network or VLAN for Corosync traffic. If your primary management network experiences a high-volume backup operation or VM migration, it can saturate the link, causing Corosync to miss heartbeats and trigger a false node fencing event.

Step 3: Retrieve and Export the Cluster Join Credentials

Once Node One has completed the cluster initialization process, you must extract its unique security token and certificate fingerprint so that Node Two can safely establish a trusted relationship.

While still logged into the Node One Web UI, remain in the Datacenter -> Cluster view. You will now see your newly created cluster listed with a status of Active. Click on the Join Information button.

A text box containing a long, encoded block of data will appear. This block contains the cluster name, the primary node's IP address, the cluster certificate fingerprint, and a secure joining key. Click the Copy Information button at the bottom of the window to save this string to your local clipboard.

Step 4: Join the Secondary Node to the Cluster

With the join credentials copied, you will now integrate Node Two into the unified management system.

Log in to the Proxmox VE Web UI of Node Two on port 8006. Navigate to Datacenter on the left-hand menu, and select Cluster. Rather than creating a cluster, click the Join Cluster button.

In the Join Information dialog box, paste the entire encoded block of text you copied from Node One into the top text area. The user interface will automatically parse the data, auto-populating the IP address, port, and SSL fingerprint fields.

You will be prompted to enter the Root Password of Node One. This is required for the initial SSH handshake and secure exchange of configuration directories.

Under the Cluster Network settings, select the appropriate local network interface for Link 0 that maps directly to the dedicated Corosync network configured on Node One. Click the Join button to execute the transition.

Warning: The node joining the cluster must not contain any pre-existing Virtual Machines (VMs) or Containers (LXCs). The joining process completely overwrites the local directory structure located at /etc/pve with the cluster configuration. Any local VM IDs that conflict with the cluster will cause critical configuration loss. Backup and migrate any local workloads to external storage before executing this step.

Once you click Join, your browser session on Node Two will eventually freeze and lose connection. This is normal. Proxmox is restarting its management API services and generating cluster-wide security keys.

Step 5: Verify Cluster Quorum and Synchronized Status

To confirm that both servers are communicating flawlessly, log back into the Proxmox Web UI using the IP address of either Node One or Node Two on port 8006.

Upon logging in, look at the left-hand resource tree. You should now see both Node One and Node Two displayed under the unified Datacenter folder. Green icons next to both hostnames indicate successful communication.

To verify the state from the command line, open an SSH terminal to either host and execute the status verification command:

pvecm status

This utility will output detailed cluster metrics. Ensure that the total number of nodes is reported as 2, the expected votes parameter equals 2, the total votes parameter equals 2, and the cluster is showing as Quorate.

Proxmox Cluster Network and Port Specifications

This operational parameter matrix details the network requirements, port configurations, and threshold values necessary to run a healthy two-node Proxmox cluster.

Troubleshooting Common Cluster Failures and Remedies

Cluster Filesystem is Locked in Read-Only Mode

• Root Cause: The cluster has lost quorum. In a two-node setup, if one node is powered down, rebooted, or experiences a network failure, the surviving node only possesses 50% of the voting pool. To prevent data corruption, the system immediately locks the local configuration filesystem (/etc/pve) into a read-only state, stopping any VM creation or configuration edits.
• Actionable Fix: Log into the surviving node via the command-line console. Force a temporary vote override to restore operational capabilities by executing: pvecm expected 1. This tells the local node that it only needs one vote to establish quorum, allowing you to modify settings and start or migrate VMs until the second node is repaired and reconnected.

Corosync Fails to Establish Handshake During Join Process

• Root Cause: Multicast or unicast traffic is being blocked by an active firewall ruleset, or there is an IP subnet mismatch on the dedicated Corosync physical link.
• Actionable Fix: Check the built-in Proxmox firewall settings. Ensure that UDP ports 5405 through 5408 are explicitly permitted on all cluster interfaces. From the terminal of Node Two, execute a manual ping targeting the specific IP address assigned to Node One's Corosync interface to confirm direct layer-2 connectivity. If the ping fails, inspect physical cabling and switch VLAN configurations.

Certificate Validation Failures and Secure Connection Refused Errors

• Root Cause: Significant time drift has occurred between the internal clocks of the two nodes. If the system time on Node Two is offset from Node One by more than a few seconds, the generated SSL certificates will fail validation checks, causing the Corosync joining procedure to error out.
• Actionable Fix: Ensure both nodes have a Network Time Protocol (NTP) service installed and configured. Install chrony on both hosts by executing apt install chrony via terminal. Force an immediate time synchronization by running chronyc tracking and verify that both systems synchronize to the same public NTP pool. Reboot the system services or reinstall the cluster certificates if necessary.

Frequently Asked Questions

Can you cluster two Proxmox servers with existing virtual machines on both?

No, you cannot safely join a node to a cluster if that node already contains active virtual machines or containers. The join process completely overwrites the local configuration directory (/etc/pve) on the joining node. To preserve your existing workloads, you must backup your VMs to an external storage server, join the empty node to the cluster, and then restore the VM backups to the newly clustered host.

Do clustered Proxmox nodes require identical physical hardware?

No, Proxmox nodes do not require identical hardware components to operate within a cluster. You can cluster servers with different CPU families, RAM capacities, and storage arrays. However, if you plan to perform live migrations of virtual machines between the nodes, both servers should ideally use compatible CPU architectures (such as both using Intel or both using AMD). If they differ, you must set the CPU type of your virtual machines to "Common KVM Processor" (kvm64) to ensure compatibility.

What is a QDevice and why is it recommended for two-node clusters?

A Quorum Device (QDevice) is a lightweight daemon that runs on a separate, external machine (such as a physical server, a virtual machine on a separate host, or even a Raspberry Pi) and acts as a third voter in your cluster. Because a two-node cluster requires more than 50% of the votes to survive, a single node failure drops the vote count to exactly 50%, locking the cluster. By introducing a QDevice, the total vote count becomes three, allowing a single surviving Proxmox node to pair with the QDevice vote (totaling 66%) to maintain safe operation.

Can I connect two Proxmox nodes over a WAN or VPN connection?

It is highly discouraged to cluster Proxmox nodes over a WAN or high-latency VPN link. Corosync relies heavily on real-time, low-latency transmission of cluster state messages. If the round-trip latency exceeds 2 milliseconds, even momentarily, the nodes will assume a network split-brain has occurred, which can cause the nodes to reboot or fence themselves to protect storage integrity.

Elevate Your Virtualization Infrastructure

Streamline your virtualization workloads and maximize uptime by pairing your newly connected Proxmox nodes with a enterprise-grade shared storage solution. Explore our advanced highly available storage architectures to unlock seamless, zero-downtime live migrations today.