Skip to content

Proxmox VE

On this page

Proxmox Virtual Environment: an open-source Type-1 platform that combines KVM VMs and LXC containers with clustering, software-defined storage, and backups in one web UI.

Basics

Proxmox VE (PVE) is a Debian-based, open-source virtualization platform. It manages:

  • KVM virtual machines — full hardware virtualization (any OS).
  • LXC containers — lightweight OS-level Linux containers (lower overhead, share host kernel).

Everything is driven from a single web UI (port 8006), a REST API, or the pve* CLI tools. Multiple nodes form a cluster with a shared configuration database.

Architecture pieces

  • pve-cluster / pmxcfs — a clustered filesystem mounted at /etc/pve that syncs config across nodes (backed by Corosync).
  • Corosync — cluster communication & membership; needs a low-latency network and a quorum (majority of votes) to make changes.
  • QEMU/KVM — the VM engine; LXC — the container engine.
  • Storage plugins — local (dir, LVM, LVM-thin, ZFS) and shared (NFS, CIFS, Ceph, iSCSI).
  • Proxmox Backup Server (PBS) — companion product for deduplicated, incremental backups.

VM vs LXC on Proxmox

KVM VM LXC container
Isolation Full (own kernel) OS-level (shares host kernel)
OS support Any (Linux, Windows, BSD) Linux only
Overhead Higher Very low
Boot Seconds Near-instant
Use Windows, kernel modules, strong isolation Lightweight Linux services

Storage models

  • LVM-thin — local, thin-provisioned, snapshots. Good single-node default.
  • ZFS — local with snapshots, replication, checksums, compression. Great for replication between two nodes.
  • Ceph — distributed, self-healing storage built into Proxmox for HA across 3+ nodes.
  • NFS/CIFS — shared network storage for ISOs, backups, and migration.

High Availability (HA)

With a quorate cluster (3+ nodes recommended) and shared/replicated storage, the HA manager restarts a VM/CT on another node if one fails. Use a QDevice as a tiebreaker if you only have two nodes.

Cheatsheet

Cluster

pvecm create my-cluster          # init cluster on first node
pvecm add 10.0.0.11              # join from a new node (run on it)
pvecm status                     # quorum & members
pvecm nodes

VMs (qm)

qm list
qm create 100 --name web --memory 4096 --cores 2 --net0 virtio,bridge=vmbr0
qm importdisk 100 image.qcow2 local-lvm
qm start 100 ; qm shutdown 100 ; qm stop 100
qm clone 100 101 --name web-clone
qm template 100                  # turn VM into a template
qm migrate 100 node2 --online
qm set 100 --agent enabled=1     # enable guest agent

Containers (pct)

pct list
pct create 200 local:vztmpl/debian-12-standard_amd64.tar.zst \
  --hostname app --memory 1024 --net0 name=eth0,bridge=vmbr0,ip=dhcp
pct start 200 ; pct enter 200 ; pct stop 200
pct clone 200 201
pct migrate 200 node2

Storage & backup

pvesm status                     # storage overview
pvesm list local
vzdump 100 --storage backupstore --mode snapshot --compress zstd
qmrestore backup.vma.zst 102     # restore a VM

Updates (no-subscription repo example)

# Use the no-subscription repo for home/lab; enterprise repo needs a subscription
apt update && apt dist-upgrade

Thumb Rules

Rules of thumb

  • Three nodes for real HA. Quorum needs a majority; two nodes can't break ties without a QDevice.
  • Separate the Corosync network from storage/VM traffic — cluster comms hate latency and congestion.
  • Prefer LXC for lightweight Linux services, KVM when you need a full/other OS or kernel isolation.
  • Ceph wants fast networking (10GbE+) and ≥3 nodes. Don't run Ceph on two slow nodes.
  • ZFS replication is the simple HA story for two nodes. Async, minutes of RPO, no shared storage needed.
  • Snapshots ≠ backups. Use vzdump/PBS for real, restorable backups stored elsewhere.
  • Enable the QEMU guest agent for clean shutdowns, fsfreeze-consistent backups, and IP reporting.
  • Don't run Proxmox on the enterprise repo without a subscription — switch to the no-subscription repo or you'll get repo errors.

Use Cases

  • Home lab / self-hosting — one box running many services as VMs/CTs.
  • SMB virtualization — open-source alternative to VMware vSphere/ESXi.
  • Edge & branch — small clusters with ZFS replication.
  • Dev/test clusters — snapshots, clones, templates, API-driven provisioning.
  • Terraform/Ansible targets — provision VMs as code on-prem (see Terraform page).

Common Issues

Cluster shows “no quorum” / can't make changes

Fewer than a majority of nodes are online. /etc/pve becomes read-only without quorum. Bring nodes back, or for two-node clusters add a QDevice tiebreaker. Check pvecm status and Corosync network health.

Enterprise repository 401 / update errors

The default enterprise repo requires a subscription. For labs, disable it and enable the no-subscription repo, then apt update.

VM has no network

Check the VM's NIC is on the right bridge (vmbr0), the bridge exists and is up (/etc/network/interfaces), and the guest has an IP. Verify the physical NIC is enslaved to the bridge.

Can't migrate a VM

Local-only storage without replication, mismatched CPU types, or a non-shared disk. Use shared storage (Ceph/NFS) or ZFS replication, and set a compatible CPU type (e.g. x86-64-v2-AES) for cross-host migration.

Backups fail or are inconsistent

Install qemu-guest-agent for fsfreeze consistency; ensure backup storage has space; prefer snapshot mode. For dedupe/incremental, use Proxmox Backup Server.

Ceph degraded / slow

Usually undersized network or too few OSDs/nodes. Ceph needs ≥3 nodes and fast (10GbE+) networking; check ceph -s and OSD health.

Best Practices

  • Plan networks: separate VLANs/NICs for management, Corosync, storage, and VM traffic.
  • Use 3+ nodes for HA, with Ceph or ZFS replication, and a QDevice tiebreaker for two-node clusters.
  • Back up to a separate system (Proxmox Backup Server) and test restores; follow 3-2-1.
  • Templates + cloud-init for repeatable VM provisioning.
  • Keep PVE patched; use the correct repo for your licensing.
  • Enable the guest agent on every VM.
  • Monitor with the built-in metrics or export to Prometheus/Grafana.
  • Protect the web UI (8006): firewall it, use TLS, strong auth/2FA, and a reverse proxy if exposed.

Official Sources