Skills
skills/bastos/skills/proxmox-admin

proxmox-admin

Installation
SKILL.md

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
Weekly Installs
269
Repository
bastos/skills
GitHub Stars
2
First Seen
Today
Security Audits
Gen Agent Trust HubWarn
SocketPass
SnykFail