Proxmox VE Administration

Overview

Proxmox VE is a server virtualization platform built on Debian. It manages KVM virtual machines and LXC containers through a web UI or CLI tools. This skill covers CLI-based administration using qm (VMs), pct (containers), and supporting utilities.

When to Use

• Creating, configuring, or managing KVM virtual machines

• Spawning and administering LXC containers

• Managing Proxmox storage, networking, or clustering

• Automating VM/container provisioning via scripts

• Troubleshooting Proxmox host or guest issues

Not for: Web UI-only workflows (use the CLI equivalents below).

Quick Reference

Tool

Purpose

qm

Manage KVM virtual machines

pct

Manage LXC containers

pvesm

Manage storage

pvecm

Manage cluster

pveam

Manage appliance/template downloads

pvesh

Access the Proxmox API from the shell

pveperf

Benchmark host performance

VM Management with qm

Creating a VM

# Create a VM with ID 100

qm create 100 --name my-vm --memory 2048 --cores 2 --sockets 1 \

  --net0 virtio,bridge=vmbr0 --ostype l26

# Create with SCSI disk on local-lvm storage (32GB)

qm create 100 --name my-vm --memory 4096 --cores 4 \

  --scsi0 local-lvm:32 --scsihw virtio-scsi-pci \

  --net0 virtio,bridge=vmbr0 --ostype l26

# Attach an ISO for installation

qm set 100 --cdrom local:iso/ubuntu-22.04-server.iso --boot order=ide2

VM Lifecycle

Command

Purpose

qm start <vmid>

Start a VM

qm shutdown <vmid>

Graceful ACPI shutdown

qm stop <vmid>

Force stop (like pulling power)

qm reboot <vmid>

Reboot a VM

qm reset <vmid>

Hard reset

qm suspend <vmid>

Suspend to RAM

qm resume <vmid>

Resume from suspend

qm destroy <vmid>

Delete VM and its disks

qm destroy <vmid> --purge

Delete VM, disks, and all related jobs

VM Configuration

# Show current config

qm config 100

# Modify hardware

qm set 100 --memory 8192

qm set 100 --cores 4

qm set 100 --balloon 2048          # dynamic memory (min)

qm set 100 --cpu cputype=host      # pass through host CPU features

qm set 100 --machine q35           # use Q35 chipset (for PCIe passthrough)

# Add/resize disks

qm set 100 --scsi1 local-lvm:50    # add 50GB disk

qm disk resize 100 scsi0 +20G      # grow existing disk by 20GB

# Networking

qm set 100 --net0 virtio,bridge=vmbr0,tag=10   # VLAN tagged

qm set 100 --net1 virtio,bridge=vmbr1           # second NIC

# Cloud-init (for automated provisioning)

qm set 100 --ide2 local-lvm:cloudinit

qm set 100 --ciuser admin --cipassword 'secret'

qm set 100 --ipconfig0 ip=10.0.0.50/24,gw=10.0.0.1

qm set 100 --sshkeys ~/.ssh/authorized_keys

qm set 100 --boot order=scsi0

# EFI / UEFI boot

qm set 100 --bios ovmf --efidisk0 local-lvm:1,efitype=4m,pre-enrolled-keys=1

# Serial console (headless)

qm set 100 --serial0 socket --vga serial0

# PCI passthrough (GPU, NIC, etc.)

qm set 100 --hostpci0 0000:01:00.0,pcie=1

Snapshots and Cloning

# Create a snapshot

qm snapshot 100 before-upgrade --description "Before kernel upgrade"

# List snapshots

qm listsnapshot 100

# Rollback to snapshot

qm rollback 100 before-upgrade

# Delete a snapshot

qm delsnapshot 100 before-upgrade

# Clone a VM (full copy)

qm clone 100 101 --name cloned-vm --full

# Clone as linked clone (shares base disk, faster)

qm clone 100 101 --name linked-vm

Templates

# Convert VM to template (irreversible)

qm template 100

# Create VM from template (linked clone)

qm clone 100 200 --name from-template

# Create VM from template (full clone)

qm clone 100 200 --name from-template --full

Migration

# Online migration to another node

qm migrate 100 node2 --online

# Offline migration

qm migrate 100 node2

Monitoring

# VM status

qm status 100

# List all VMs

qm list

# Show running processes/agent info

qm agent 100 ping

qm agent 100 get-osinfo

# Monitor interface (QEMU monitor)

qm monitor 100

Container Management with pct

Creating a Container

# Download a template first

pveam update

pveam available --section system

pveam download local debian-12-standard_12.2-1_amd64.tar.zst

# Create container with ID 200

pct create 200 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \

  --hostname my-ct --memory 1024 --cores 2 \

  --rootfs local-lvm:8 \

  --net0 name=eth0,bridge=vmbr0,ip=dhcp \

  --password 'secret' --unprivileged 1

# Create with static IP

pct create 201 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \

  --hostname web-ct --memory 2048 --cores 2 \

  --rootfs local-lvm:16 \

  --net0 name=eth0,bridge=vmbr0,ip=10.0.0.51/24,gw=10.0.0.1 \

  --nameserver 1.1.1.1 --unprivileged 1

Container Lifecycle

Command

Purpose

pct start <ctid>

Start container

pct shutdown <ctid>

Graceful shutdown

pct stop <ctid>

Force stop

pct reboot <ctid>

Reboot container

pct destroy <ctid>

Delete container and its volumes

pct enter <ctid>

Open a shell inside the container

pct exec <ctid> -- <cmd>

Run a command inside the container

pct console <ctid>

Attach to container console

Container Configuration

# Show config

pct config 200

# Modify resources

pct set 200 --memory 4096

pct set 200 --cores 4

pct set 200 --swap 1024

# Add mount point (bind mount from host)

pct set 200 --mp0 /mnt/data,mp=/data

# Add additional storage volume

pct set 200 --mp1 local-lvm:50,mp=/var/lib/data

# Networking

pct set 200 --net0 name=eth0,bridge=vmbr0,ip=10.0.0.60/24,gw=10.0.0.1

pct set 200 --net1 name=eth1,bridge=vmbr1,ip=dhcp

# Features (nesting, FUSE, NFS)

pct set 200 --features nesting=1

pct set 200 --features nesting=1,fuse=1,mount=nfs

# DNS

pct set 200 --nameserver "1.1.1.1 8.8.8.8" --searchdomain example.com

# Start on boot

pct set 200 --onboot 1 --startup order=1,up=30

Container Snapshots and Cloning

# Snapshot

pct snapshot 200 clean-install

# Rollback

pct rollback 200 clean-install

# Clone

pct clone 200 201 --hostname cloned-ct --full

Storage Management

# List storage pools

pvesm status

# List content of a storage

pvesm list local

pvesm list local-lvm

# Add storage (examples)

pvesm add dir my-backup --path /mnt/backup --content backup

pvesm add nfs nfs-share --server 10.0.0.5 --export /exports/pve --content images,vztmpl

pvesm add lvm my-lvm --vgname my-vg --content rootdir,images

pvesm add zfspool my-zfs --pool rpool/data --content rootdir,images

# Remove storage

pvesm remove my-backup

# Download ISO

wget -P /var/lib/vz/template/iso/ https://example.com/image.iso

Networking

# List network interfaces

cat /etc/network/interfaces

# Common bridge configuration (in /etc/network/interfaces)

# auto vmbr0

# iface vmbr0 inet static

#     address 10.0.0.1/24

#     bridge-ports eno1

#     bridge-stp off

#     bridge-fd 0

# Apply network changes

ifreload -a

Cluster Management

# Create a new cluster

pvecm create my-cluster

# Join an existing cluster

pvecm add 10.0.0.1

# Show cluster status

pvecm status

# List cluster nodes

pvecm nodes

# Remove a node (run from a remaining node)

pvecm delnode nodename

# Check quorum

pvecm expected 1    # force quorum (dangerous, single-node recovery only)

Firewall

# Start or stop the node firewall service

pve-firewall start

pve-firewall stop

pve-firewall status

# Enable datacenter firewall in /etc/pve/firewall/cluster.fw

# [OPTIONS]

# enable: 1

#

# Manage rules via config files. Add remote management allow rules before

# enabling restrictive policies.

# Datacenter: /etc/pve/firewall/cluster.fw

# Node:       /etc/pve/nodes/<node>/host.fw

# VM/CT:      /etc/pve/firewall/<vmid>.fw

Backup and Restore

# Backup a VM

vzdump 100 --storage local --mode snapshot --compress zstd

# Backup a container

vzdump 200 --storage local --mode stop --compress zstd

# Backup all guests

vzdump --all --storage local --mode snapshot --compress zstd --mailto admin@example.com

# Restore a VM

qmrestore /var/lib/vz/dump/vzdump-qemu-100-*.vma.zst 100

# Restore a container

pct restore 200 /var/lib/vz/dump/vzdump-lxc-200-*.tar.zst

# Restore to different storage

qmrestore /var/lib/vz/dump/vzdump-qemu-100-*.vma.zst 100 --storage local-lvm

Common Provisioning Patterns

Cloud-Init VM from Template

# 1. Create base VM and install OS, then convert to template

qm template 9000

# 2. Clone and customize with cloud-init

qm clone 9000 110 --name web-server --full

qm set 110 --ciuser deploy --sshkeys ~/.ssh/authorized_keys

qm set 110 --ipconfig0 ip=10.0.0.110/24,gw=10.0.0.1

qm set 110 --nameserver 1.1.1.1

qm start 110

Batch Create Containers

for i in $(seq 1 5); do

  CTID=$((300 + i))

  pct create $CTID local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \

    --hostname "worker-${i}" --memory 1024 --cores 2 \

    --rootfs local-lvm:8 \

    --net0 name=eth0,bridge=vmbr0,ip=10.0.0.$((60 + i))/24,gw=10.0.0.1 \

    --unprivileged 1 --start 1

done

Import Disk Image (e.g., cloud image)

# Download a cloud image

wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img

# Import to a VM

qm disk import 100 jammy-server-cloudimg-amd64.img local-lvm

# Attach the imported disk

qm set 100 --scsi0 local-lvm:vm-100-disk-0

qm set 100 --boot order=scsi0

Troubleshooting

Problem

Solution

VM won't start

Check qm config <vmid>, verify storage exists with pvesm status

"TASK ERROR: can't lock file"

Check running tasks first; if the task is gone, use qm unlock <vmid> or pct unlock <ctid>

Container has no network

Check bridge exists: brctl show; verify firewall rules

Disk full on storage

pvesm status to check usage; lvs for LVM thin pools

Cluster quorum lost

pvecm expected 1 on surviving node (single-node recovery only)

Migration fails

Ensure same CPU type or use --online with live migration; check network between nodes

Backup fails with lock error

qm unlock <vmid> or pct unlock <ctid>

Slow disk I/O in VM

Use --scsihw virtio-scsi-single and disk options like ,iothread=1,discard=on

Guest agent not responding

Install qemu-guest-agent in the VM and enable: qm set <vmid> --agent 1

Useful Paths

Path

Contents

/etc/pve/

Cluster-wide config (pmxcfs)

/etc/pve/qemu-server/<vmid>.conf

VM configuration files

/etc/pve/lxc/<ctid>.conf

Container configuration files

/etc/pve/storage.cfg

Storage definitions

/etc/pve/nodes/

Per-node configuration

/var/lib/vz/

Default local storage root

/var/lib/vz/template/iso/

ISO images

/var/lib/vz/template/cache/

Container templates

/var/lib/vz/dump/

Backup files

/var/log/pve/tasks/

Task logs