Virtualization5 min read

Proxmox Architecture

Open-source virtualization management — KVM VMs and LXC containers on Debian

What is Proxmox VE?

Proxmox Virtual Environment at a Glance

Open-source server virtualization management platform built on Debian GNU/Linux
Manages two compute workload types side by side: KVM virtual machines and LXC containers
Ships a full web UI on port 8006 (HTTPS), a REST API, and CLI tools (qm, pct, pvesh, pvecm, etc.)
AGPL v3 licensed — free to run in production; optional paid enterprise repository & support subscriptions
Built-in clustering, live migration, HA, backup, software-defined networking, and multiple storage backends

Note

Proxmox is not a hypervisor itself — it is a management layer on top of KVM (for VMs) and LXC (for containers). The actual hypervisor is the Linux kernel's KVM module.

Bare-Metal Server (x86_64)

Debian Linux + Proxmox Packages

KVM (kernel module)

VM 100 (Windows)

VM 101 (Ubuntu)

LXC Runtime

CT 200 (Debian)

CT 201 (Alpine)

Core Components

pve-manager

Web interface & API server. Written in Perl with an ExtJS frontend. Listens on https://<node>:8006. Every action in the UI maps to a REST API call — anything clickable is scriptable.

pve-cluster (pmxcfs + Corosync)

Cluster-wide filesystem mounted at /etc/pve/. Backed by SQLite, replicated in real time via Corosync. All node configs, VM configs, firewall rules, and HA state live here.

pve-firewall

Distributed firewall — rules defined per-datacenter, per-host, or per-VM/CT. Configs stored in /etc/pve/firewall/. Uses iptables (legacy) or nftables (Proxmox 8+) under the hood.

pve-ha-manager

High availability manager. Monitors HA-flagged resources and coordinates automatic failover. Relies on Corosync for quorum and fencing for safety (STONITH).

qemu-server

KVM VM management daemon. Generates QEMU command lines from declarative config files. Configs: /etc/pve/qemu-server/<vmid>.conf. CLI tool: qm.

pve-container

LXC container management. Creates and manages system containers. Configs: /etc/pve/lxc/<ctid>.conf. CLI tool: pct.

Tip

The /etc/pve/ directory is not a normal filesystem — it is a FUSE mount backed by pmxcfs. Edits propagate to all cluster nodes in real time. Never store large files here.

KVM Virtual Machines in Proxmox

Each Proxmox KVM VM is ultimately a QEMU process running on the host. Proxmox reads the .conf file, translates it into a qemu-system-x86_64 command line with dozens of flags, and manages the process lifecycle.

Example VM Config

text

bash


    /etc/pve/qemu-server/
      100.conf

console


    # /etc/pve/qemu-server/100.conf
    boot: order=scsi0;ide2;net0
cores: 4
memory: 8192
name: ubuntu-server
net0: virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,firewall=1
scsi0: local-lvm:vm-100-disk-0,size=64G,iothread=1,ssd=1
scsihw: virtio-scsi-single
machine: q35
cpu: host
ostype: l26
agent: 1
balloon: 2048
numa: 0
onboot: 1

Machine Types

i440fx (Legacy)

Emulates the classic Intel 440FX chipset
Maximum compatibility — works with old OSes
PCI bus only (no native PCIe)
BIOS boot (SeaBIOS)
Good default if you don't need passthrough

q35 (Modern)

Emulates the Intel ICH9/Q35 chipset
Native PCIe — required for PCI passthrough
UEFI boot (OVMF) support
Secure Boot capable
Required for GPU passthrough, NVMe passthrough

CPU Types

CPU Type	Description	Use Case
`host`	Passes all host CPU flags to guest	Best performance; prevents migration to different CPU family
`kvm64`	Minimal x86_64 baseline	Safe for migration between any x86_64 hosts
`qemu64`	QEMU's default virtual CPU	Maximum compatibility, some perf trade-offs
`x86-64-v2-AES`	Microarch level 2 + AES-NI	Good balance: migratable within modern hardware
Named models (`Skylake-Server`, `EPYC-Rome`, etc.)	Expose a well-defined CPU feature set	Migratable within same-generation hardware

Warning

Using cpu: host gives the best performance but prevents live migration to a node with a different CPU generation. For mixed clusters, use a named model or x86-64-v2-AES.

LXC Containers in Proxmox

Proxmox LXC containers are system containers — they run a full init system (systemd, OpenRC) and behave like lightweight VMs. This is fundamentally different from Docker's application containers that run a single process.

What LXC Containers Share with the Host

Kernel — same kernel as the Proxmox host (cannot run Windows)
Kernel modules — containers cannot load their own modules
Hardware clock

What LXC Containers Isolate

Mount namespace — own root filesystem
PID namespace — PID 1 inside is container's init
Network namespace — own interfaces, IPs, routes
UTS namespace — own hostname
IPC namespace — own shared memory, semaphores
User namespace (unprivileged only) — UID mapping

Privileged vs Unprivileged Containers

Privileged Container

Container UID 0 = Host UID 0
Root inside container is real root on the host
Container escape = full host compromise
Easier to set up (no UID mapping issues)
Needed for some workloads (NFS server, Docker-in-LXC)
Avoid unless required

Unprivileged Container

Container UID 0 maps to Host UID 100000+
Root inside container is an unprivileged user on host
Container escape = nobody-level access
Uses user namespaces for UID/GID mapping
Default and recommended for all new containers
Some features may need features: flags in config

console


    # Unprivileged container UID mapping in config
    lxc.idmap: u 0 100000 65536
lxc.idmap: g 0 100000 65536
    # Container root (UID 0) → Host UID 100000
    # Container UID 1000 → Host UID 101000

KVM vs LXC — Side-by-Side Comparison

Feature	KVM Virtual Machine	LXC Container
Kernel	Own kernel (any OS)	Shared host kernel (Linux only)
Boot time	~10-30 seconds	~1-2 seconds
RAM overhead	~256 MB+ (kernel + OS + workload)	Minimal (~10-30 MB base)
Isolation	Strong — hardware-level (VMCS, EPT)	Namespace-based — kernel shared
OS support	Any: Windows, BSD, Linux, etc.	Linux only
Live migration	Yes (pre-copy memory)	Yes (CRIU-based, less mature)
Device passthrough	Full PCI/VFIO, USB, GPU	Limited (bind mounts, some device nodes)
Density	Lower — each VM has full kernel	Higher — share kernel, minimal overhead
Security profile	Stronger (hardware boundary)	Weaker (kernel attack surface shared)
Config location	`/etc/pve/qemu-server/<vmid>.conf`	`/etc/pve/lxc/<ctid>.conf`
CLI tool	`qm`	`pct`
Best for	Windows, untrusted workloads, GPU, custom kernels	Linux services, high density, fast provisioning

Proxmox Cluster Topology

🖥

Node 1 (pve1)

VM 100, CT 200

Corosync ring

🖥

Node 2 (pve2)

VM 101, CT 201

Corosync ring

🖥

Node 3 (pve3)

VM 102, CT 202

All nodes share /etc/pve/ via pmxcfs — configs are always in sync

Cross-References

KVM/QEMU Internals

For deep dives into hypervisor types, VMCS, VMX transitions, and how KVM works at the CPU level, see Virt 01 — Hypervisors.

Linux Namespaces

For detailed namespace mechanics (mount, PID, net, user, UTS, IPC, cgroup, time), see Virt 02 — Namespaces.