Proxmox VE (Virtual Environment) Comprehensive Cheatsheet

1. Installation and Initial Setup

Minimum Requirements

64-bit x86 CPU with virtualization support (Intel VT-x or AMD-V)
4GB RAM (minimum), 8GB+ recommended (more for ZFS or Ceph workloads)
20GB disk space for Proxmox installation (SSD/NVMe recommended)
Ethernet network interface (10GbE+ recommended for cluster/Ceph traffic)

Installation Methods

Download the latest Proxmox VE 8.x ISO from https://www.proxmox.com/en/downloads
Create a bootable USB with dd, Rufus, balenaEtcher, or Ventoy
Boot from USB and run the graphical or terminal installer (terminal mode added in PVE 8.2)

Post-Installation Initial Configuration

Bash

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Update system repositories
apt update && apt full-upgrade -y

# Disable enterprise repositories (optional, for no-subscription use)
sed -i 's/^deb/#deb/' /etc/apt/sources.list.d/pve-enterprise.list
sed -i 's/^deb/#deb/' /etc/apt/sources.list.d/ceph.list 2>/dev/null || true

# Add the public (no-subscription) repository for Proxmox VE 8 (Debian 12 "bookworm")
echo "deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription" \
  > /etc/apt/sources.list.d/pve-public.list

# Refresh and install recommended packages
apt update
apt install -y pve-headers chrony

Accessing Web Interface

Default URL: https://[SERVER_IP]:8006
Initial Credentials: root@pam
Best Practice: Create a separate admin user, enable TFA/WebAuthn, and restrict root login

Web Interface Key Sections

Datacenter: Cluster-wide management, SDN, backup jobs, permissions
Nodes: Individual server resources and services
Virtual Machines (VMs): VM management
Containers (LXC): Container management
Storage: Storage configuration
Access Control: Users, groups, realms, API tokens, TFA

3. Node and Cluster Management

Node Status Commands

Bash

1
2
3
4
5
6
7
8
9
10
11
12
# Check node status
pvesh get /nodes

# View cluster status
pvecm status

# Join an existing cluster
pvecm add [MASTER_NODE_IP]

# Create a new cluster
pvecm create [CLUSTER_NAME]

Cluster Configuration

Minimum 3 nodes recommended for quorum and high availability
Use similar hardware/configuration for predictable HA behavior
Use a dedicated, low-latency network for Corosync (separate from storage)
Configure multiple Corosync links (links 0–7) for redundancy
Time synchronization via chrony is mandatory

4. Virtual Machine Creation and Configuration

Create VM via CLI

Bash

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Basic VM creation (modern defaults)
qm create 100 \
  --name ubuntu-server \
  --memory 2048 \
  --cores 2 \
  --cpu host \
  --machine q35 \
  --bios ovmf \
  --efidisk0 local-lvm:1,efitype=4m,pre-enrolled-keys=1 \
  --scsihw virtio-scsi-single \
  --net0 virtio,bridge=vmbr0

# Attach an installation ISO and start
qm set 100 --ide2 local:iso/ubuntu-24.04.iso,media=cdrom
qm set 100 --boot order='scsi0;ide2;net0'
qm start 100

VM Management Commands

Bash

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# List VMs
qm list

# Stop VM (graceful via ACPI: qm shutdown)
qm stop 100

# Reboot VM
qm reboot 100

# Clone VM
qm clone 100 101 --name ubuntu-server-clone

# Delete VM (also purge from job/HA configs)
qm destroy 100 --purge

5. Container (LXC) Management

Create LXC Container

Bash

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Download an up-to-date template first
pveam update
pveam available --section system | grep ubuntu
pveam download local ubuntu-24.04-standard_24.04-2_amd64.tar.zst

# Create an Ubuntu container
pct create 200 \
  local:vztmpl/ubuntu-24.04-standard_24.04-2_amd64.tar.zst \
  --hostname webserver \
  --memory 1024 \
  --cores 2 \
  --rootfs local-lvm:8 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp \
  --unprivileged 1 \
  --features nesting=1

Container Commands

Bash

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# List containers
pct list

# Start / stop / reboot
pct start 200
pct stop 200
pct reboot 200

# Enter a container shell
pct enter 200

# Execute a command inside a container
pct exec 200 -- apt update

6. Storage Configuration

Storage Types

Directory: File-based storage on the local filesystem
LVM / LVM-Thin: Block storage on local disks
ZFS (local) / ZFS over iSCSI: Snapshots, replication, compression
NFS / CIFS (SMB): Network file shares
iSCSI: Block storage over IP
Ceph RBD / CephFS: Distributed block and file storage
Proxmox Backup Server (PBS): Deduplicated, incremental backups
GlusterFS is deprecated and removed from the GUI in PVE 9 (planned)

Configure Local Storage

Bash

1
2
3
4
5
# Add a directory-based backup storage
pvesm add dir local-backup \
  --path /backup \
  --content backup

NFS Storage Setup

Bash

1
2
3
4
5
6
# Add NFS storage
pvesm add nfs nfs-storage \
  --server 192.168.1.100 \
  --export /volume/backup \
  --content backup,iso,vztmpl

Proxmox Backup Server Storage

Bash

1
2
3
4
5
6
7
8
# Attach a PBS datastore as backup target
pvesm add pbs pbs-main \
  --server pbs.example.com \
  --datastore main \
  --username backup@pbs \
  --password 'secret' \
  --fingerprint <SHA256-FINGERPRINT>

7. Network Configuration

Bridge Configuration

Persist bridges in /etc/network/interfaces (or via the GUI/ifupdown2), then apply:

Bash

1
2
ifreload -a

Example stanza:

auto vmbr1
iface vmbr1 inet manual
    bridge-ports eth1
    bridge-stp off
    bridge-fd 0

VLAN-Aware Bridges

auto vmbr0
iface vmbr0 inet static
    address 192.168.1.10/24
    gateway 192.168.1.1
    bridge-ports eno1
    bridge-stp off
    bridge-fd 0
    bridge-vlan-aware yes
    bridge-vids 2-4094

SDN (Software-Defined Networking)

Fully integrated in PVE 8 and managed under Datacenter → SDN
Supports zones (Simple, VLAN, QinQ, VXLAN, EVPN), VNets, and subnets
Apply changes cluster-wide with Apply in the SDN view or pvesh set /cluster/sdn

8. Backup and Restore Operations

Backup VM/Container

Bash

1
2
3
4
5
6
7
8
9
10
11
12
# Backup a VM (vzdump replaces the old qm backup wrapper)
vzdump 100 --mode snapshot --storage local --compress zstd

# Backup an LXC container
vzdump 200 --mode snapshot --storage pbs-main

# Restore a VM
qmrestore /var/lib/vz/dump/vzdump-qemu-100-*.vma.zst 101

# Restore an LXC container
pct restore 201 /var/lib/vz/dump/vzdump-lxc-200-*.tar.zst

Backup Features

Schedule and retention policies via Datacenter → Backup
Encrypted, incremental, deduplicated backups with Proxmox Backup Server
File-level restore from the GUI for both VMs and containers
Notification system overhauled in PVE 8.1+ (/etc/pve/notifications.cfg) with SMTP and Gotify targets

9. High Availability (HA) Setup

HA Configuration Steps

Ensure cluster has quorum (≥3 nodes or a QDevice)
Use shared storage (Ceph, NFS, iSCSI, ZFS-over-iSCSI) or storage replication for ZFS
Add resources to an HA group with a restart policy
Configure fencing (watchdog-based via softdog or hardware watchdogs)

Bash

1
2
3
4
5
6
# Add a VM to HA management
ha-manager add vm:100 --state started --max_restart 3 --max_relocate 1

# List HA-managed resources
ha-manager status

10. User Management and Permissions

Realms and Authentication

pam: Linux PAM users on the host
pve: Proxmox VE built-in authentication
LDAP, Active Directory, and OpenID Connect (OIDC) realms supported

Create User and Assign Permissions

Bash

1
2
3
4
5
6
7
8
9
10
# Add a user
pveum user add admin@pve --comment "Admin User"
pveum passwd admin@pve

# Assign role on a path (ACL)
pveum acl modify / --user admin@pve --role Administrator

# Create an API token (no password, recommended for automation)
pveum user token add admin@pve automation --privsep 0

TFA / WebAuthn

TOTP and WebAuthn (passkeys, hardware keys) are fully supported
Recovery keys can be generated per user

11. Firewall Configuration

Datacenter / Node / VM Firewalls

Bash

1
2
3
4
5
6
7
8
9
10
11
12
13
# Enable the firewall at the datacenter level
pvesh set /cluster/firewall/options --enable 1

# Enable firewall on a node
pvesh set /nodes/[NODE]/firewall/options --enable 1

# Add a rule allowing SSH on a node
pvesh create /nodes/[NODE]/firewall/rules \
  --action ACCEPT \
  --type in \
  --proto tcp \
  --dport 22

IP sets, aliases, and security groups live under Datacenter → Firewall
nftables backend is available as an opt-in option (still tech preview in PVE 8.x)

12. Templates and Cloud-Init

Create Template

Bash

1
2
3
4
5
6
# Convert a VM to a template
qm template 9000

# Linked clone from a template
qm clone 9000 101 --name new-vm

Cloud-Init

Bash

1
2
3
4
5
6
7
# Attach a Cloud-Init drive and configure
qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --ciuser ubuntu --cipassword 'changeme' \
            --sshkeys ~/.ssh/authorized_keys \
            --ipconfig0 ip=dhcp \
            --serial0 socket --vga serial0

13. Migration Techniques

Live and Offline Migration

Bash

1
2
3
4
5
6
7
8
9
# Online migration (default for running VMs)
qm migrate 100 [TARGET_NODE] --online

# Offline migration with local-disk transfer
qm migrate 100 [TARGET_NODE] --with-local-disks

# Bulk migration of all guests on a node
pvenode migrateall [TARGET_NODE]

Import from Other Hypervisors

Native ESXi import (introduced in PVE 8.2): Datacenter → Storage → Add → ESXi, then import VMs directly from the GUI or with qm importovf / qm importdisk

14. Monitoring and Alerts

Performance Monitoring

Bash

1
2
3
4
5
6
7
8
9
# Disk and CPU benchmark
pveperf

# Node status (JSON)
pvesh get /nodes/[NODE]/status

# Live resource view
pvesh get /cluster/resources --type vm

Built-in metric server support for InfluxDB and Graphite (Datacenter → Metric Server)
Notification matchers (PVE 8.1+) route alerts (backup, replication, fencing, updates) to SMTP, Gotify, or other endpoints

15. Command-Line Tools

Key CLI Tools

qm: VM management
pct: LXC container management
pvesh: REST API shell
pvecm: Cluster management
pvesm: Storage management
pveum: User/ACL management
pveceph: Ceph cluster management
pveam: Appliance/template manager
vzdump / qmrestore: Backup and restore
ha-manager: HA resource management
proxmox-boot-tool: Manage systemd-boot / GRUB on ZFS/BTRFS setups

16. API Usage and Automation

API Access

REST API at https://[SERVER]:8006/api2/json
Prefer API tokens with privilege separation over password auth
Official tooling: pvesh (CLI), proxmoxer (Python), Terraform provider bpg/proxmox, Ansible collection community.general.proxmox*

Bash

1
2
3
4
# Example: list VMs via curl using an API token
curl -k -H "Authorization: PVEAPIToken=admin@pve!automation=<UUID>" \
  https://pve.example.com:8006/api2/json/cluster/resources?type=vm

17. Ceph Integration

Basic Ceph Setup

Proxmox VE 8.x ships with Ceph Reef (18.2) and Quincy (17.2); newer releases enable Squid (19.2) where supported.

Bash

1
2
3
4
5
6
7
8
9
10
11
12
# Install Ceph on each node (choose the release)
pveceph install --repository no-subscription --version reef

# Initialize Ceph networking
pveceph init --network 10.10.10.0/24

# Create monitors, managers, OSDs, and a pool
pveceph mon create
pveceph mgr create
pveceph osd create /dev/nvme0n1
pveceph pool create vmdata --add_storages 1

CephFS can be created from the GUI and used for ISOs, templates, and backups
Erasure-coded pools are configurable from the GUI in PVE 8.x

18. Performance Optimization

Recommended Optimizations

Use virtio-scsi-single with iothread=1 and discard=on for SSD/NVMe
Use the virtio NIC model; enable multiqueue for high-throughput workloads
Use cpu: host for best performance (or a stable model like x86-64-v2-AES for migration compatibility)
Enable KSM only when memory overcommit is desired; it is throttled by default
Use NUMA pinning and hugepages for large VMs
Configure IOMMU and VFIO for PCIe passthrough (e.g., GPUs, NICs)
Prefer ZFS with adequate ARC sizing, or Ceph with NVMe DB/WAL devices
Disable mitigations only when threat model permits; document the change

19. Troubleshooting

Common Commands

Bash

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Journal for a service
journalctl -u pve-cluster -xe
journalctl -u corosync -xe

# Cluster filesystem status
pvecm status
systemctl status pve-cluster pveproxy pvedaemon pvestatd

# Network state
ip -br addr
bridge link

# Storage health
pvesm status
zpool status
ceph -s

Useful Logs

/var/log/syslog, journalctl
/var/log/pveproxy/access.log
Task logs under Node → Tasks (also at /var/log/pve/tasks/)

20. Production Best Practices

Take regular, tested backups — ideally to a Proxmox Backup Server with offsite replication
Separate management, Corosync, storage, and VM traffic on different NICs/VLANs
Standardize on templates and Cloud-Init for reproducible deployments
Implement HA with proper fencing and quorum (use a QDevice for 2-node clusters)
Monitor with InfluxDB/Grafana and configure notification targets
Apply updates regularly; subscribe to the enterprise repository for production
Use role-based access control with API tokens and TFA/WebAuthn enabled
Front the web UI with a reverse proxy or restrict port 8006 via firewall; install a trusted TLS certificate (ACME/Let's Encrypt is built in)
Audit logs and enable the cluster firewall with a default-deny posture
Plan capacity for Ceph and ZFS (RAM, OSD count, failure domains) before scaling

Note: Always refer to the official Proxmox VE documentation (https://pve.proxmox.com/pve-docs/) and the pve-devel/pve-user mailing lists for the most up-to-date information. This cheatsheet targets Proxmox VE 8.x on Debian 12 "bookworm"; Proxmox VE 9 (Debian 13 "trixie") is in development and may change defaults noted above.

Proxmox VE

Continue Learning