A two-node cluster sounds simple at first, but as soon as one node fails, the remaining node lacks the necessary majority of votes (quorum), and the cluster switches to read-only mode. This is where the QDevice (Quorum Device) comes into play: It acts as a lightweight third party that provides an additional vote, thereby maintaining quorum even when one node fails. Since the QDevice does not host virtual machines or provide storage, it can run on a small VM, an LXC container, or a dedicated mini-server—ideally on a current Debian or Ubuntu distribution, so that the dependencies for Proxmox VE 9 are met without issues.
Before starting the installation, you should have two already configured Proxmox VE 9 nodes in the cluster (e.g., pve1.lab.local and pve2.lab.local). Additionally, a third, lightweight Linux system is needed to serve as the QDevice (e.g., qdevice.lab.local). SSH access with root users and root privileges must be available between all three machines. A working name resolution (DNS or /etc/hosts) and synchronized time via NTP are also essential for Corosync to communicate correctly.
Installation on the QDevice
On the intended QDevice, we first run a package update and then install the two required packages:
apt update
apt install corosync-qnetd corosync-qdevice -y
corosync-qnetd provides the daemon that listens on the QDevice, while corosync-qdevice provides the client component used by the Proxmox nodes to communicate with the QDevice. After installation, we activate and start the service:
systemctl enable corosync-qnetd
systemctl start corosync-qnetd
With systemctl status corosync-qnetd, you can quickly check whether the service is active and running without errors.
Installation on the Proxmox Nodes
On both Proxmox servers, we only need the client package:
apt update
apt install corosync-qdevice -y
No additional daemon needs to be started here; communication takes place via the already running qnetd on the QDevice.
Integrating the QDevice into the Cluster
Now we switch to one of the Proxmox nodes (e.g., pve1) and run the setup command:
pvecm qdevice setup qdevice.example.local
This command establishes a connection to the QDevice, configures it as an additional voter, and automatically distributes the necessary keys and configuration files. It is important that the hostname or IP address of the QDevice is resolvable and reachable from both cluster nodes; otherwise, the setup will fail.
Verifying the Setup
After successful setup, the cluster status can be queried with the familiar command:
pvecm status
The output should show an entry for the QDevice under the “Quorum information” section (Node ID 0, Votes 1) and indicate the state as “Quorate”. Example excerpt:
Quorum information
------------------
Date: Sat Oct 18 22:05:13 2025
Quorum provider: corosync_votequorum
Nodes: 2
...
Quorate: Yes
...
Votequorum information
----------------------
Expected votes: 3
Total votes: 3
Quorum: 2
...
Membership information
----------------------
Nodeid Votes Name
1 1 pve1 (local)
2 1 pve2
0 1 Qdevice
The presence of the QDevice with one vote and the quorate status confirms that the setup is working.
Testing Failover Resilience
To validate the resilience, we shut down one of the Proxmox nodes (or disconnect its network connection). On the remaining node, we run pvecm status again. If the cluster remains quorate and shows the QDevice as an active voter, the QDevice has fulfilled its task: the remaining node can continue working, virtual machines remain running, and HA operations are still possible.
Troubleshooting
If the setup does not work as expected, it is recommended to check the following points:
- Port 5403/tcp must be open between the Proxmox nodes and the QDevice (qnetd listens here by default).
- Hostnames must resolve correctly; a missing DNS entry or incorrect /etc/hosts entries can lead to connection problems.
- Time synchronization: All systems should have a running NTP client so that Corosync timestamps are consistent.
- Logs often provide detailed clues:
journalctl -u corosync-qnetdon the QDevice andjournalctl -u corosyncon the Proxmox nodes show connection errors, authentication issues, or configuration conflicts.
Conclusion
A QDevice is a lean but effective addition to two-node Proxmox VE clusters. It provides the missing vote needed to maintain quorum even when a node fails, without requiring a third full Proxmox host. The setup can be done with just a few packages and short commands, and after successful testing, the system offers a stable HA environment—ideal for smaller installations, edge environments, or test labs where resources are to be saved but failover protection is still required.
References
https://www.saturnme.com/how-to-install-and-configure-qdevice-for-a-2-node-proxmox-ve-cluster/