proxmox-ve

name

proxmox-ve

description

Manage QEMU/KVM virtual machines on Proxmox VE using the qm command-line tool. Use when working with Proxmox VE for: (1) VM lifecycle operations (create, start, stop, destroy), (2) Cloning VMs and creating templates, (3) Snapshot management and rollback, (4) VM migration between nodes, (5) Disk operations (import, resize, move), (6) Guest agent interactions, (7) Cloud-init configuration, (8) Any task involving the 'qm' command or Proxmox VM management.

Proxmox VE VM Management

Comprehensive VM management for Proxmox VE using the qm command-line tool with helper scripts for common operations and reference documentation.

Quick Start

The qm command is the primary tool for managing QEMU/KVM virtual machines in Proxmox VE:

# List all VMs
qm list

# Check VM status
qm status <vmid>

# Start/stop VM
qm start <vmid>
qm shutdown <vmid>     # Graceful shutdown
qm stop <vmid>         # Force stop

Core Operations

1. VM Lifecycle Management

Use the provided vm_lifecycle.py script for safe VM operations with validation:

# Start VM and wait for it to be running
python3 scripts/vm_lifecycle.py start 100

# Stop VM gracefully
python3 scripts/vm_lifecycle.py stop 100

# Force stop VM
python3 scripts/vm_lifecycle.py stop 100 --force

# Restart VM
python3 scripts/vm_lifecycle.py restart 100

# Check status
python3 scripts/vm_lifecycle.py status 100

# Destroy VM (with confirmation)
python3 scripts/vm_lifecycle.py destroy 100

Or use qm commands directly:

# Create new VM
qm create 100 --name myvm --memory 2048 --cores 2 --net0 virtio,bridge=vmbr0

# Configure VM
qm set 100 --memory 4096 --cores 4
qm set 100 --scsi0 local-lvm:32

# VM state management
qm start 100
qm shutdown 100
qm stop 100
qm reboot 100
qm destroy 100

2. Cloning VMs

Use the clone_vm.py script for validated cloning:

# Full clone (independent copy)
python3 scripts/clone_vm.py 100 200 --name cloned-vm

# Linked clone (faster, depends on source)
python3 scripts/clone_vm.py 100 201 --name test-vm --linked

# Clone to different node
python3 scripts/clone_vm.py 100 202 --target node2 --name remote-clone

Or use qm directly:

# Full clone
qm clone 100 200 --name cloned-vm --full

# Linked clone
qm clone 100 201 --name test-vm

# Clone to different node with storage
qm clone 100 202 --target node2 --storage node2-storage --full

3. Template Management

Use the create_template.py script for best-practice template creation:

# Get preparation guidance
python3 scripts/create_template.py 900

# Convert to template after preparation
python3 scripts/create_template.py 900 --skip-prep

The script guides through proper VM preparation:

• Cleaning temporary files and logs
• Removing SSH host keys
• Clearing machine-id
• Installing cloud-init
• System updates

Or use qm directly (after manual preparation):

# Add cloud-init drive
qm set 900 --ide2 local-lvm:cloudinit

# Convert to template
qm template 900

# Clone template to create new VMs
qm clone 900 100 --name web-server --full

4. Snapshot Management

Use the snapshot_manager.py script for snapshot operations:

# Create snapshot (auto-generated name)
python3 scripts/snapshot_manager.py create 100

# Create snapshot with custom name and description
python3 scripts/snapshot_manager.py create 100 \
  --name before-upgrade \
  --description "Before kernel upgrade"

# Create snapshot with VM state (RAM)
python3 scripts/snapshot_manager.py create 100 --vmstate

# List all snapshots
python3 scripts/snapshot_manager.py list 100

# Delete snapshot
python3 scripts/snapshot_manager.py delete 100 before-upgrade

# Rollback to snapshot
python3 scripts/snapshot_manager.py rollback 100 before-upgrade

Or use qm directly:

# Create snapshot
qm snapshot 100 before-upgrade --description "Before upgrade" --vmstate

# List snapshots
qm listsnapshot 100

# Rollback
qm rollback 100 before-upgrade

# Delete snapshot
qm delsnapshot 100 before-upgrade

5. Migration

Migrate VMs between nodes in the cluster:

# Online migration (VM stays running)
qm migrate 100 node2 --online

# Offline migration
qm shutdown 100
qm migrate 100 node2
qm start 100

# Migration with bandwidth limit
qm migrate 100 node2 --online --bwlimit 100000  # 100 MB/s

6. Disk Operations

# Add new disk
qm set 100 --scsi1 local-lvm:50

# Resize disk (grow only)
qm disk resize 100 scsi0 +20G

# Move disk to different storage
qm disk move 100 scsi0 --storage faster-storage

# Import external disk
qm disk import 100 /tmp/disk.qcow2 local-lvm
qm set 100 --scsi2 local-lvm:vm-100-disk-2

# Remove disk
qm set 100 --delete scsi1

7. Guest Agent Operations

Requires qemu-guest-agent installed in VM:

# Enable guest agent
qm set 100 --agent 1

# Execute guest commands
qm guest cmd 100 fsfreeze-freeze   # Freeze filesystem
qm guest cmd 100 fsfreeze-thaw     # Thaw filesystem
qm guest cmd 100 shutdown          # Guest shutdown

# Execute arbitrary commands
qm guest exec 100 -- /bin/ls -la /tmp

# Set user password
qm guest passwd 100 root

8. Cloud-Init Configuration

# Add cloud-init drive (required)
qm set 100 --ide2 local-lvm:cloudinit

# Configure user and credentials
qm set 100 --ciuser admin --cipassword securepass

# Configure network (static IP)
qm set 100 --ipconfig0 ip=192.168.1.100/24,gw=192.168.1.1

# Or use DHCP
qm set 100 --ipconfig0 ip=dhcp

# Set DNS
qm set 100 --nameserver 8.8.8.8 --searchdomain example.com

# Add SSH keys
qm set 100 --sshkeys ~/.ssh/authorized_keys

# View generated cloud-init config
qm cloudinit dump 100 user
qm cloudinit dump 100 network

When to Use What

Use Scripts When

• Need validation and safety checks
• Want automatic waiting/polling for state changes
• Working interactively and want guided experience
• Need consistent error handling

Use qm Commands When

• Writing automation scripts
• Need maximum flexibility and control
• Using advanced options not in helper scripts
• Integrating with other tools

Reference Documentation

Complete Command Reference

See references/qm-command-reference.md for comprehensive documentation of all qm commands, options, and flags.

Step-by-Step Workflows

See references/common-workflows.md for detailed guides on:

• Creating VMs from scratch
• Template creation and usage
• Snapshot-based workflows
• Cloning strategies
• Migration procedures
• Disk management tasks
• Cloud-init setup

Best Practices

See references/best-practices.md for:

• VM ID allocation strategies
• Template management guidelines
• Snapshot strategies and pitfalls
• Storage considerations
• CPU and memory configuration
• Security best practices
• Troubleshooting guides

Common Patterns

Template-Based VM Deployment

# 1. Create and configure template (once)
python3 scripts/create_template.py 900 --skip-prep

# 2. Deploy multiple VMs from template
for i in {1..3}; do
  qm clone 900 $((100 + i)) --name "web-$i" --full
  qm set $((100 + i)) --ipconfig0 ip=192.168.1.$((100 + i))/24,gw=192.168.1.1
  qm start $((100 + i))
done

Safe Update Workflow

# 1. Create snapshot before update
python3 scripts/snapshot_manager.py create 100 \
  --name before-update \
  --description "Before system update"

# 2. Perform update
# ... update operations ...

# 3. If issues, rollback
python3 scripts/snapshot_manager.py rollback 100 before-update
python3 scripts/vm_lifecycle.py start 100

# 4. If successful, clean up snapshot
python3 scripts/snapshot_manager.py delete 100 before-update

Development Clone Pattern

# 1. Create linked clone from production VM
qm clone 100 200 --name dev-test

# 2. Start and test
qm start 200

# 3. Destroy when done
qm stop 200
qm destroy 200

Important Considerations

VM IDs

• Valid range: 100-999,999,999
• Must be unique across cluster
• Consider using ID ranges for organization (100-199 for templates, 200-299 for production, etc.)

Snapshots Are Not Backups

• Snapshots live on same storage (single point of failure)
• Have performance overhead
• Not designed for long-term retention
• Use Proxmox Backup Server or vzdump for actual backups

Template Preparation Is Critical

• Always clean machine-specific data before templating
• Remove SSH host keys: rm /etc/ssh/ssh_host_*
• Clear machine-id: truncate -s 0 /etc/machine-id
• Install cloud-init and qemu-guest-agent
• Update system before templating

Storage Format Matters

• raw: Best performance, no overhead, fixed size (recommended for production)
• qcow2: Space efficient, snapshot support, slight overhead (good for templates)

CPU Type for Migration

• Use generic CPU types (kvm64) for clusters where migration is needed
• Use host CPU type for best performance on single-host deployments
• Online migration requires matching CPU families

Scripts Directory

• vm_lifecycle.py - Safe VM lifecycle operations with validation and state monitoring
• clone_vm.py - VM cloning with validation and common options
• snapshot_manager.py - Comprehensive snapshot management (create, list, delete, rollback)
• create_template.py - Template creation with best-practice guidance

All scripts support --help for detailed usage information.