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 with a static IP and resolvable hostname), follow the official "Install Proxmox VE on Debian 13 Trixie" wiki. The core steps:

wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg \
  -O /usr/share/keyrings/proxmox-archive-keyring.gpg   # verify the SHA256 listed on the wiki
cat > /etc/apt/sources.list.d/proxmox.sources <<'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
apt update && apt full-upgrade
apt install proxmox-default-kernel && reboot
apt install proxmox-ve postfix open-iscsi chrony
# then remove the stock Debian kernel packages as described on the wiki

arm64

Since 2026-08-05 there are official arm64 ISOs and repositories. Supported hardware is NVIDIA Grace Hopper / Vera; other UEFI + ACPI ARMv9 servers are best-effort, and Raspberry Pi-class boards are not supported. See Reference.

Fix repositories after install (no subscription?)

The installer enables the Enterprise repo, which fails apt update with an authorization error when the node has no subscription key. For lab/non-production nodes, switch to the no-subscription repo (the GUI does the same under Node -> Updates -> Repositories):

# 9.x uses deb822 .sources files; disable an entry with "Enabled: no"
echo "Enabled: no" >> /etc/apt/sources.list.d/pve-enterprise.sources
cat > /etc/apt/sources.list.d/proxmox.sources <<'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
apt update && apt full-upgrade

Do the same for the Ceph entry in /etc/apt/sources.list.d/ceph.sources unless the node has a subscription: point its URI at http://download.proxmox.com/debian/ceph-<release> with component no-subscription. The browser "no valid subscription" nag is cosmetic; removing it is a community-scripts one-liner — but consider the EUR 120 per socket-year Community tier, which gives 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 disk import 101 old-image.qcow2 local-zfs          # import existing disk (older alias: qm importdisk)
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 --section system | grep debian-13     # pick the current template name
pveam download local <debian-13-standard_...tar.zst>
pct create 201 local:vztmpl/<debian-13-standard_...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 192.0.2.11                # on each additional node (IP of an existing member)
pvecm status                        # quorum: 3 nodes => expected votes 3

Requirements: same PVE major version, no guests on the joining node (VMIDs could clash), dedicated low-latency NIC, UDP 5405-5412 open, clocks synced. For a 2-node (or any even-sized) cluster, add a QDevice on separate hardware:

# on the external arbiter (a small Debian box, not a cluster member):
apt install corosync-qnetd
# on all cluster nodes:
apt install corosync-qdevice
# on one cluster node:
pvecm qdevice setup <QDEVICE-IP>
pvecm status                            # the QDevice now shows up with a vote

Enable HA and the CRS load balancer

Mark guests managed: ha-manager add ct:201 (or via GUI per guest). Check ha-manager status. Placement constraints are HA rules (node affinity and resource affinity/anti-affinity), which replaced HA groups in 9.0.

Then pick a scheduler in Datacenter -> Options -> Cluster Resource Scheduling: dynamic mode (9.2+) uses real CPU/memory usage, and enabling automatic rebalancing lets the CRM migrate HA guests to reduce imbalance (threshold tunable; exclude a resource with its auto-rebalance property). See Reference.

For planned network or switch maintenance (9.2+), disarm HA cluster-wide so watchdogs are released and a flapping cluster network cannot trigger fencing:

ha-manager crm-command disarm-ha freeze   # or: ignore (lets you start/stop/migrate HA guests by hand)
# ... maintenance ...
ha-manager crm-command arm-ha

Warning

While disarmed, HA recovers nothing. Keep the window short.

Hyperconverged Ceph

pveceph install --repository no-subscription   # Tentacle 20.2 default on 9.2; pick enterprise with a subscription
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 (local disks or, officially supported since 4.2, an S3-compatible bucket with a local cache), and add a user + API token with backup permission on the datastore. On the PVE side:

pvesm add pbs pbs-main --server pbs.example.com --datastore main \
  --username 'backup@pbs!pve' --password <token-secret> \
  --fingerprint "<sha256 from PBS dashboard>" \
  --prune-backups keep-daily=7,keep-weekly=4
vzdump 101 --storage pbs-main --mode snapshot \
  --fleecing enabled=1,storage=local-lvm --notes-template '{{guestname}}/{{node}}'

Schedule via Datacenter -> Backup (jobs are run by pvescheduler). For off-site copies enable client-side encryption on the PBS storage entry and keep the key outside the cluster. Live restore boots a VM while its data still streams in: qmrestore <backup-volid> 101 --live-restore 1 (or the GUI checkbox). 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 mediated devices, e.g. --hostpci0 0000:01:00.0,mdev=<nvidia-type> (types are listed in the GUI). Prefer cluster-wide resource mappings (Datacenter -> Resource Mappings) so guests can move between nodes. Live migration of passed-through devices requires the mapping to be marked live-migration-capable; the docs call it experimental and only recent NVIDIA GPUs are known to work.

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). Click Apply (writes and reloads the per-node network configuration). 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.

Upgrade from PVE 8 to 9

PVE 8 reached EOL in 2026-08, so any remaining 8.x nodes should be upgraded. Condensed from the official "Upgrade from 8 to 9" wiki (read it in full first; upgrade one node at a time after migrating its guests away):

apt update && apt dist-upgrade           # reach the latest 8.4.x first
pve8to9 --full                           # checker script; fix every FAIL, review every WARN
# Ceph clusters: be on Ceph Squid 19.2 BEFORE the PVE major upgrade
sed -i 's/bookworm/trixie/g' /etc/apt/sources.list   # Debian base repos
# also switch the PVE and Ceph repo entries to trixie (see the wiki)
apt update && apt dist-upgrade
reboot
pve8to9 --full                           # re-run after the reboot

Tip

The Ceph Squid 19.2 repository reaches EOL in 2026-09, so plan the Squid -> Tentacle 20.2 Ceph upgrade as a separate step after the PVE upgrade.

Import VMware ESXi VMs

Datacenter -> Storage -> Add -> ESXi (credentials for an ESXi host; vCenter works but is slower), then per VM: select it in the storage content view and click "Import"; the wizard maps disks, NICs, and OS type to PVE equivalents. Shut the source VM down first, or use live-import, which boots the VM on PVE while its disks copy in the background. Separately, OVA/OVF appliances can be imported from file-based storages that carry the import content type.

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: enable fleecing (--fleecing enabled=1,storage=<fast local>); for qcow2-on-NFS, schedule snapshot ops with the VM stopped (file-based internal snapshots block the VM).
  • apt update fails on enterprise.proxmox.com: no subscription key, or a key for the wrong CPU architecture (arm64 hosts need arm64 keys) — add a valid key or set Enabled: no on the enterprise entry.
  • 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