Skip to content

How-to guides

Context

Task-oriented recipes for the operations a Proxmox admin repeats: install, fix repositories, create guests, cluster, hyperconverge, back up, pass through GPUs, segment networks, import from VMware, and recover from the classic failure modes.

Install PVE 9.2

Download the ISO from the Proxmox downloads page, write it to USB, boot, and follow the graphical installer (ext4/xfs/ZFS root choices; Btrfs supported). Post-install, the node is reachable at https://<ip>:8006. Verify hardware fitness:

pveperf                        # CPU + disk (fsync) baseline; compare against expectations
lscpu | grep -E "Model name|Virtualization"

For Debian-first installs (PVE on top of an existing Debian 13), add the Proxmox repo and install the metapackage:

echo "deb [signed-by=/etc/apt/keyrings/proxmox-archive-keyring.gpg] https://enterprise.proxmox.com/debian/pve trixie pve-enterprise" > /etc/apt/sources.list.d/pve-install-repo.list
wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring.gpg -O /etc/apt/keyrings/proxmox-archive-keyring.gpg
apt update && apt full-upgrade
apt install proxmox-default-kernel

Fix repositories after install (no subscription?)

The installer enables the Enterprise repo, which 403s without a subscription key. For lab/non-production nodes, switch to the no-subscription repo:

# disable enterprise, enable no-subscription (9.x uses deb822 .sources files)
sed -i 's/^Types: deb/#&/; s/^URIs: https:\/\/enterprise.proxmox.com/# disabled: &/' /etc/apt/sources.list.d/pve-enterprise.sources
cat > /etc/apt/sources.list.d/pve-no-subscription.sources <<'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Signed-By: /etc/apt/keyrings/proxmox-archive-keyring.gpg
EOF
apt update && apt full-upgrade

Also disable the Ceph enterprise repo unless you hold a Ceph subscription (ceph-enterprise.sources) and enable ceph-<codename>.sources accordingly. The browser "no valid subscription" nag is cosmetic; removing it is a community-scripts one-liner — but consider the EUR 120/yr Community tier, which legalizes Enterprise-repo access cheaply.

Create a VM (qm)

qm create 101 --name web01 --cores 4 --memory 4096 \
  --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-single \
  --ostype l26 --agent enabled=1
qm set 101 --scsi0 local-zfs:32,ssd=1,discard=on     # 32G zvol
qm importdisk 101 old-image.qcow2 local-zfs           # import existing disk
qm set 101 --ide2 local:iso/debian-13.iso,media=cdrom # installer ISO
qm start 101

For cloud-init guests, add --cicustom or the cloudinit drive (qm set 101 --ide2 local-zfs:cloudinit) and set sshkeys, ipconfig0. Templates + linked clones: qm template 101 then qm clone 101 150 --name web-clone.

Create an LXC container (pct)

pveam update && pveam available
pveam download local debian-13-standard_13.2-1_amd64.tar.zst
pct create 201 local:vztmpl/debian-13-standard_13.2-1_amd64.tar.zst \
  --hostname ct01 --cores 2 --memory 2048 --rootfs local-zfs:8 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp --unprivileged 1 --features nesting=1
pct start 201 && pct enter 201

Prefer unprivileged (mapped-root) containers; enable nesting only when the workload needs it (Docker-in-LXC).

Create a cluster and add nodes

pvecm create lab-cluster            # on the first node
pvecm add 10.0.0.11                 # on each additional node (IP of an existing member)
pvecm status                        # quorum: 3 nodes => expected votes 3

Requirements: same PVE major version, empty/compatible guests, dedicated low-latency NIC, UDP 5405-5412 open, clocks synced. For a 2-node cluster, add a QDevice on separate hardware:

apt install corosync-qdevice            # on both nodes
# on the qdevice host (can be a PVE node or separate Debian box):
apt install corosync-qnetd
pvecm qdevice setup                     # then pvecm qdevice add <qnetd-host>

Enable HA and the CRS load balancer

Mark guests managed: ha-manager add ct:201 (or via GUI per guest). Check ha-manager status. Then enable dynamic load balancing in Datacenter -> Options (HA settings, 9.2+): CRS migrates HA guests to minimize node imbalance; sensitivity is tunable. For planned maintenance windows: ha-manager disarm-ha, do the work, ha-manager arm-ha — resource state is preserved, no fencing storms.

Hyperconverged Ceph

pveceph install                     # packages (Squid or Tentacle on 9.2)
pveceph init --network 10.10.10.0/24    # dedicated cluster network strongly recommended
pveceph osd create /dev/nvme0n1     # repeat per OSD, per node (3+ nodes, 3+ OSDs)
pveceph mon create; pveceph mgr create
pveceph pool create rbd-data        # then use as storage: content images, rootdir

Keep Ceph on its own network; ~1 GB RAM per TB used storage; monitor with ceph -s and the GUI Ceph panel.

Back up to Proxmox Backup Server

On the PBS side, install PBS 4.x, create a datastore, add a user + API token. On the PVE side:

pvesm add pbs pbs-main --server pbs.lab.lan --datastore main \
  --fingerprint "<sha256 from PBS>" --password <token-secret> \
  --content backup --backup-retention keep-daily=7,keep-weekly=4
vzdump 101 --storage pbs-main --mode snapshot --notes-template '{{guestname}}/{{node}}'

Schedule via Datacenter -> Backup jobs (or pvescheduler). Enable encryption on the PBS datastore for off-site copies; live restore (qm restore --live) boots guests while data still streams in. Fleecing keeps busy guests responsive during backup windows.

GPU passthrough (for AI/VDI hosts)

  1. Enable IOMMU: intel_iommu=on (or amd_iommu=on) plus iommu=pt in kernel cmdline; verify dmesg | grep -e DMAR -e IOMMU.
  2. Bind the GPU to vfio-pci by vendor:device ID in /etc/modprobe.d/vfio.conf (options vfio-pci ids=10de:2684,10de:22ba), update initramfs, reboot.
  3. Add the whole GPU to the VM: qm set 101 --hostpci0 0000:01:00.0,pcie=1,x-vga=1.
  4. NVIDIA vGPU (licensed) uses --hostpci0 ... ,mdev=nvidia-63 style mediated devices; vGPU live migration is supported on NVIDIA today (broader vendors on roadmap).

Segment networks with SDN

Datacenter -> SDN: create a zone (VLAN on vmbr0, or EVPN for routed overlays), then a VNet with a subnet (gateway + DHCP range if using the DHCP IPAM tech preview). Apply (the SDN controller writes per-node configs). Guests then attach via --net0 virtio,bridge=<vnet> — from the guest's perspective a VNet is just another bridge. For multi-site L2 stretch, use an EVPN zone with BGP controllers; 9.2 adds WireGuard/BGP fabrics, route maps, and IPv6 underlay.

Import VMware ESXi VMs

Datacenter -> Storage -> Add -> ESXi (point at the ESXi host or an offline ESXi OVA/VMDK mount), then per-VM: "Import" on the storage content browser selects disks, NICs, and maps them to PVE equivalents (qm importdisk under the hood). Works against live ESXi 6.5+ or offline volumes; OVA/OVF vendor-extension coverage keeps expanding per roadmap.

Troubleshooting

  • Quorate: No after an abrupt outage: do NOT blindly pvecm expected 1 on multi-node clusters — first check pvecm status, corosync links, and switch ports; expected 1 is break-glass for single-node recovery.
  • VM won't start, "lock 'xxx'": a stale lock from a crashed task — qm unlock 101 (verify no running task first in the GUI task log).
  • Web UI unreachable but guests fine: systemctl restart pveproxy pvedaemon; check journalctl -u pveproxy -e; certificate expiry — ACME can renew node certs automatically.
  • Slow cluster actions: corosync latency — corosync-cfgtool -s per link; move to a dedicated NIC; check for bond-masked single links.
  • Backup slows the guest: switch to snapshot mode with fleecing on PBS; for qcow2-on-NFS, schedule snapshot ops with the VM stopped (file-based internal snapshots block the VM).
  • Disk performance sanity: pveperf for fsync latency; inside guests use virtio-scsi-single + discard=on + ssd=1 on ZFS/Ceph; enable iothread for busy disks.

Sources