Table of Contents

Proxmox Virtual Environment

Table of Contents

Overview

The Proxmox Virtual Environment is a complete, open-source server management platform for enterprise virtualization. It tightly integrates the KVM hypervisor and Linux Containers (LXC), software-defined storage and networking functionality, on a single platform. With the integrated web-based user interface you can manage VMs and containers, high availability for clusters, or the integrated disaster recovery tools with ease.

Prerequisites

Hardware Requirements

Minimum Requirements:

  • CPU: 64-bit processor with Intel VT-x or AMD-V support
  • RAM: 2GB (4GB recommended for production)
  • Storage: 32GB available disk space (SSD recommended)
  • Network: Gigabit Ethernet adapter

Recommended for Production:

  • CPU: Multi-core 64-bit processor with virtualization support
  • RAM: 16GB or more
  • Storage: Multiple drives for redundancy (RAID configuration)
  • Network: Multiple network interfaces for separation of management and VM traffic

Software Requirements

  • Compatible server hardware with UEFI or BIOS boot support
  • Network access for downloading packages and updates
  • Basic knowledge of Linux command line
  • Understanding of virtualization concepts

Installation

Download Proxmox VE ISO

  1. Visit the official Proxmox website: https://www.proxmox.com/en/downloads
  2. Download the latest Proxmox VE ISO image
  3. Verify the checksum (recommended)

Create Installation Media

USB Installation:

# Linux
dd if=proxmox-ve_*.iso of=/dev/sdX bs=1M status=progress

# Windows - use tools like Rufus or Balena Etcher

DVD Installation:

  • Burn the ISO to a DVD using your preferred burning software

Installation Process

  1. Boot from Installation Media

    • Configure BIOS/UEFI to boot from USB/DVD
    • Ensure virtualization extensions are enabled in BIOS

  2. Start Installation

    • Select "Install Proxmox VE (Graphical)"
    • Accept the license agreement

  3. Configure Storage

    • Select target hard disk
    • Choose filesystem (ZFS recommended for production)
    • Configure ZFS options if selected

  4. Set Location and Timezone

    • Select your country, timezone, and keyboard layout

  5. Administrator Account

    • Set root password (use strong password)
    • Provide email address for notifications

  6. Network Configuration

    • Configure management network interface
    • Set hostname (FQDN format: hostname.domain.com)
    • Configure IP address (static recommended)
    • Set gateway and DNS servers

  7. Installation Summary

    • Review settings and start installation
    • Installation typically takes 10-15 minutes

  8. First Boot

Post-Installation Configuration

After the installation is complete, there are some configuration changes that should be performed to ensure the Proxmox server is secure and properly configured.

Non-Production APT Repository

To access non-production Proxmox packages, you need to modify your repository sources. Edit the sources.list file:

vi /etc/apt/sources.list

Add the following lines to the bottom of the file (replace "bookworm" with your Debian version if different):

deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription
deb http://download.proxmox.com/debian/ceph-quincy bookworm no-subscription

Next, disable the production repository by commenting out these lines in pve-enterprise.list:

vi /etc/apt/sources.list.d/pve-enterprise.list

Comment out this line:

#deb https://enterprise.proxmox.com/debian/pve bookworm pve-enterprise

Similarly, disable the enterprise repository for Ceph by commenting out these lines in ceph.list:

vi /etc/apt/sources.list.d/ceph.list

Comment out this line:

# deb https://enterprise.proxmox.com/debian/ceph-quincy bookworm enterprise

Automated Script for Repository Configuration:

The following script will execute the above tasks in one step:

#!/bin/bash
echo "Configure the 'non-subscription' repositories for pve and ceph...."
echo "deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription" | tee -a /etc/apt/sources.list
echo "deb http://download.proxmox.com/debian/ceph-quincy bookworm no-subscription" | tee -a /etc/apt/sources.list

echo "Disable the Enterprise repositories for pve and ceph...."
sed -i '/^deb/s/^/# /' /etc/apt/sources.list.d/pve-enterprise.list
sed -i '/^deb/s/^/# /' /etc/apt/sources.list.d/ceph.list

echo "Update package list...."
apt update

echo "Configuration complete!"

VLAN Configuration

After your server reboots, you can configure VLAN support in the Proxmox web UI:

  • Select server.
  • Go to “Network” in the menu.
  • Select the Linux bridge (vmbr0).
  • Click “Edit” at the top of the window.
  • Check the box that says “VLAN aware.”
  • Press “OK.”

Disable Subscription Popup

To remove the subscription popup, run the following command:

sed -Ezi.bak "s/(Ext.Msg.show\(\{\s+title: gettext\('No valid sub)/void\(\{ \/\/\1/g" /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.js && systemctl restart pveproxy.service

Afterward, reboot your server, log out of the Proxmox web GUI, clear your browser cache, and then log back in.

Virtual Machine Setup

There are a number of different ways to create a template in Proxmox that can then be deployed using Terraform or CLI (qm).

Create Cloud-Init Clone

The following script will download the Cloud-Init image and create a VM template from it.

VMID=9000
TEMPLATENAME="debian12-cloudinit"
TEMPLATEURL="https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2"
FILE="debian-12-genericcloud-amd64.qcow2"

pushd /root/
if [ -f $FILE ]; then
   echo "Image ($FILE) exists."
else
   echo "Image ($FILE) does not exist. Downloading...."
   wget $TEMPLATEURL
fi
popd

qm create $VMID --name $TEMPLATENAME
qm set $VMID --scsi0 local-lvm:0,import-from=/root/$FILE
qm template $VMID

QEMU Guest Agent Setup

  1. Enable QEMU Guest Agent:

    • In the Proxmox web interface, select your VM.
    • Go to "Hardware" > "Add" > "QEMU Guest Agent".
    • Start the VM if it's not already running.

  2. Install QEMU Guest Agent (Debian/Ubuntu):

    apt update
apt install qemu-guest-agent

  3. Enable and Start the QEMU Agent:

    systemctl enable qemu-guest-agent
systemctl start qemu-guest-agent

  4. Verify Installation:

    To verify that the QEMU Guest Agent is running:

    systemctl status qemu-guest-agent

Complete script to install, enable, and start the QEMU guest agent:

#!/bin/bash
# Install and configure QEMU Guest Agent
apt update
apt install qemu-guest-agent -y
systemctl enable qemu-guest-agent
systemctl start qemu-guest-agent

# Verify installation
systemctl status qemu-guest-agent --no-pager

Security Considerations

Initial Security Hardening

Change Default SSH Configuration:

# Edit SSH configuration
vi /etc/ssh/sshd_config

# Recommended changes:
# Port 22 (consider changing to non-standard port)
# PermitRootLogin prohibit-password
# PasswordAuthentication no (after setting up SSH keys)
# Protocol 2

# Restart SSH service
systemctl restart sshd

Configure SSH Key Authentication:

# Generate SSH key pair (on your local machine)
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# Copy public key to Proxmox server
ssh-copy-id root@your-proxmox-ip

Set Up Fail2Ban:

apt install fail2ban -y
systemctl enable fail2ban
systemctl start fail2ban

# Create custom jail configuration
cat > /etc/fail2ban/jail.local << EOF
[DEFAULT]
bantime = 3600
findtime = 600
maxretry = 3

[sshd]
enabled = true
port = ssh
filter = sshd
logpath = /var/log/auth.log
maxretry = 3

[proxmox]
enabled = true
port = https,http,8006
filter = proxmox
logpath = /var/log/daemon.log
maxretry = 3
bantime = 3600
EOF

systemctl restart fail2ban

Network Security

Configure Firewall Rules:

# Allow SSH (adjust port if changed)
pvesh create /cluster/firewall/groups --group ssh --comment "SSH Access"
pvesh create /cluster/firewall/groups/ssh --enable 1 --action ACCEPT --proto tcp --dport 22

# Allow Proxmox web interface
pvesh create /cluster/firewall/groups --group proxmox-web --comment "Proxmox Web Interface"
pvesh create /cluster/firewall/groups/proxmox-web --enable 1 --action ACCEPT --proto tcp --dport 8006

Regular Security Updates:

# Create update script
cat > /usr/local/bin/proxmox-update.sh << 'EOF'
#!/bin/bash
# Proxmox security update script
echo "Starting Proxmox security updates..."
apt update
apt upgrade -y
apt autoremove -y
echo "Updates completed on $(date)" >> /var/log/proxmox-updates.log
EOF

chmod +x /usr/local/bin/proxmox-update.sh

# Schedule weekly updates (optional)
echo "0 2 * * 0 root /usr/local/bin/proxmox-update.sh" >> /etc/crontab

Troubleshooting

Common Issues and Solutions

1. Subscription Repository Errors

# Error: "repository 'https://enterprise.proxmox.com/debian/pve' doesn't have a Release file"
# Solution: Disable enterprise repository and enable no-subscription repository
sed -i '/^deb/s/^/# /' /etc/apt/sources.list.d/pve-enterprise.list
echo "deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription" >> /etc/apt/sources.list
apt update

2. VM Won't Start - Hardware Virtualization

# Check if hardware virtualization is enabled
grep -E '(vmx|svm)' /proc/cpuinfo

# If empty, enable VT-x/AMD-V in BIOS/UEFI

3. Network Connectivity Issues

# Check network configuration
ip addr show
ip route show

# Test connectivity
ping 8.8.8.8
systemctl status networking

4. Storage Issues

# Check storage status
pvesm status
df -h
lsblk

# Check ZFS pools (if using ZFS)
zpool status
zfs list

5. Web Interface Not Accessible

# Check Proxmox web service
systemctl status pveproxy
systemctl status pvedaemon

# Check if ports are listening
netstat -tulpn | grep :8006

# Restart web services
systemctl restart pveproxy pvedaemon

Log File Locations

System Logs

  • /var/log/syslog - General system logs
  • /var/log/daemon.log - Daemon logs (including Proxmox)
  • /var/log/auth.log - Authentication logs

Proxmox Specific Logs

  • /var/log/pveproxy/access.log - Web interface access
  • /var/log/pve/tasks/ - Task logs
  • /var/log/libvirt/qemu/ - VM logs

Additional Resources

Official Documentation

Useful Commands Reference

VM Management

# List all VMs
qm list

# Start VM
qm start <vmid>

# Stop VM
qm stop <vmid>

# Create VM from template
qm clone <template-id> <new-vmid> --name <vm-name>

Container Management

# List containers
pct list

# Start container
pct start <ctid>

# Enter container
pct enter <ctid>

Storage Management

# List storage
pvesm status

# Add storage
pvesm add <type> <storage-id> --path <path>

Best Practices

  1. Regular Backups: Set up automated backups for critical VMs
  2. Resource Monitoring: Monitor CPU, memory, and storage usage
  3. Documentation: Keep detailed records of VM configurations
  4. Testing: Test disaster recovery procedures regularly
  5. Updates: Keep Proxmox and guest systems updated
  6. Security: Implement proper access controls and network segmentation

This guide provides a comprehensive foundation for deploying and managing Proxmox VE. For production environments, consider additional clustering, high availability, and backup strategies based on your specific requirements.

Edit this page