proxmox

What this skill does

# Proxmox VE

**Production infrastructure demands production discipline. Every Proxmox configuration must be secure by default,
redundant where it matters, and automated where possible.**

## Route to Reference

- **VM, LXC, and OCI container management** — [`${CLAUDE_SKILL_DIR}/references/vm-and-lxc.md`]: VM vs LXC vs OCI
  comparison, OCI container support (PVE 9.1 tech preview), Docker-on-Proxmox decision guidance, configuration options,
  template workflows, linked vs full clone trade-offs
- **Storage backends** — [`${CLAUDE_SKILL_DIR}/references/storage-backends.md`]: Backend capability matrix, ZFS tuning
  (ARC/L2ARC/SLOG/volblocksize), Ceph configuration, LVM-Thin monitoring, storage selection decision tree
- **Networking** — [`${CLAUDE_SKILL_DIR}/references/networking.md`]: Bridge configuration, VLAN layout, bonding modes,
  SDN zones (VXLAN/EVPN), MTU considerations, OVS vs Linux bridge, firewall lockout prevention
- **Clustering and HA** — [`${CLAUDE_SKILL_DIR}/references/clustering-and-ha.md`]: Corosync configuration, quorum math,
  QDevice setup, split-brain prevention, fencing methods, HA groups, migration, quorum loss recovery
- **API and automation** — [`${CLAUDE_SKILL_DIR}/references/api-automation.md`]: REST API architecture, pvesh/qm/pct
  reference, Terraform patterns, cloud-init customization (cicustom, network v2), hookscript lifecycle, CI/CD pipelines
- **Backup strategies** — [`${CLAUDE_SKILL_DIR}/references/backup-strategies.md`]: vzdump modes, PBS architecture,
  encryption key management, garbage collection safety, verification jobs, retention policies, off-site sync patterns

## Guest Management

<guest-management>

### VM vs LXC vs OCI Decision

- **Default to LXC** for trusted Linux workloads — near-zero overhead, high density
- **Use VMs** when the workload requires: non-Linux OS, full kernel isolation, PCIe passthrough, or live migration
- **Use OCI containers** (PVE 9.1+, tech preview) for single-purpose microservices from Docker Hub/GHCR — lightweight
  deployment without a Docker VM. Not suitable for multi-container stacks or workloads requiring Docker Compose
- **Use a Docker VM** for full Docker/Compose/Kubernetes workflows, multi-container stacks, or advanced networking
  (macvlan, overlay). Still the most flexible and compatible option for container-heavy workloads
- **Use unprivileged containers** (default) — they map container UID 0 to a non-privileged host UID, preventing
  container escape attacks
- Only use privileged containers when unprivileged mode is incompatible (specific device access, certain NFS mounts)

### VM Configuration

- Use **VirtIO** drivers for disk and network — mandatory for production performance
- Enable **QEMU Guest Agent** inside every VM for graceful shutdown, snapshot consistency, and IP address reporting
- Use **OVMF (UEFI) + Q35 machine type** for PCIe passthrough and Secure Boot
- Set CPU type to `host` for maximum performance in homogeneous clusters; use `x86-64-v2-AES` or the lowest common CPU
  generation when live migration across different CPU generations is required
- Enable **memory ballooning** for dynamic RAM management
- Enable **NUMA** topology for VMs with many cores on multi-socket hosts

### Container Configuration

- Set **explicit memory limits** — containers without limits can exhaust host RAM
- Enable **nesting** (`features: nesting=1`) only when required (Docker inside LXC)
- For Docker workloads in LXC: unprivileged + `nesting=1` + `keyctl=1` — but note this is **unsupported** and can break
  on host updates (CVE-2025-52881 broke Docker-in-LXC setups; workaround: `lxc.apparmor.profile: unconfined`)
- Use **bind mounts** to share host directories, not NFS/CIFS mounts inside the container
- PVE 9.0 removed cgroup v1 entirely — containers requiring cgroup v1 must move to VMs

### OCI Application Containers (PVE 9.1 — Tech Preview)

- Pull OCI images from Docker Hub/GHCR/Quay and run as LXC containers — no Docker engine required
- **Limitations:** no in-place updates, no Docker Compose, no orchestration, no shell in most containers
- **Use for:** single-purpose lightweight services; **use a Docker VM** for multi-container stacks
- See [`${CLAUDE_SKILL_DIR}/references/vm-and-lxc.md`] for full OCI details, Docker-on-Proxmox decision guide, and
  Docker VM best practices

### Templates and Cloning

- Build templates with the guest agent and cloud-init pre-installed
- Convert to template: `qm template <vmid>` or backup as `.tar.gz` for containers
- Use **linked clones** for development/ephemeral workloads (fast, shared base disk)
- Use **full clones** for production (independent, no template dependency)

</guest-management>

## Storage

<storage>

### Backend Selection

- **Local redundancy, data integrity, snapshots** → ZFS
- **Local snapshots/clones without ZFS overhead** → LVM-Thin
- **Shared storage for HA clusters (3+ nodes)** → Ceph
- **Simple shared storage (existing NAS/SAN)** → NFS or iSCSI
- **Deduplicated backups** → PBS

### ZFS Rules

- Use HBA in IT mode — never hardware RAID controllers with write-back cache
- **ARC sizing:** cap explicitly in `/etc/modprobe.d/zfs.conf`; 25-30% of host RAM for mixed workloads. PVE 8.1+
  defaults to 10% (max 16GB) for new installs. Rule of thumb: 2GB base + 1GB per TB of storage
- Set `ashift=12` for 4K sector disks (most modern drives); incorrect ashift halves IOPS due to sector misalignment
- **Volblocksize** (VMs on zvols): 16k for mirrors/RAID10; increase for wide RAIDZ to reduce write amplification. Can
  only be set at zvol creation
- **Recordsize** (containers on datasets): tune per workload — 8k for Postgres, 16k for MariaDB, 1M for large sequential
  files
- Enable `compression=lz4` — can actually increase I/O performance by writing less data to disk
- **SLOG:** 8-32GB enterprise NVMe with power-loss protection; only holds ~5s of write data. Benefits sync-heavy
  workloads (databases, NFS)
- **L2ARC:** only if ARC hit ratio is low and adding RAM is not possible; size 5-20x RAM; budget 1GB RAM per 50GB of
  L2ARC for metadata
- Schedule regular scrubs (weekly or monthly)
- Plan capacity upfront — ZFS pools cannot be shrunk
- Never create swap on a ZFS zvol — causes blocking I/O during backups

### Ceph Rules

- Minimum 3 nodes for proper quorum and data distribution
- Dedicated 10GbE+ network for Ceph traffic (25GbE+ recommended for NVMe OSDs), separate from Corosync — Ceph rebalance
  traffic saturates links and causes Corosync instability
- Use SSD/NVMe for OSD WAL/DB
- Dedicated disks for OSDs — never share with the host OS
- PVE 9.0 defaults to Ceph Squid (v19.2)

### Storage Anti-Patterns

- Running ZFS or Ceph on top of hardware RAID with write-back cache — defeats data integrity guarantees
- Overprovisioning LVM-Thin without monitoring — a full thin pool causes I/O errors for all guests on that pool
- Storing backups on the same physical disks as production data
- Letting ZFS ARC consume unbounded RAM — causes VM crashes when the hypervisor and VMs compete for memory

</storage>

## Networking

<networking>

### Core Model

Every guest connects to a **Linux bridge**. Use **VLAN-aware bridges** (single bridge with 802.1Q tagging) instead of
per-VLAN bridges. The VLAN-aware checkbox must be explicitly enabled — it is off by default.

### VLAN Best Practices

- Place the **management interface on a dedicated VLAN** — never share with guest traffic
- Configure **trunk ports** on physical switches for the Proxmox host — frames with VLAN IDs not allowed by the switch
  are silently dropped
- Assign VLAN tags per guest in the network configuration
- Verify no double-tagging mismatch between Proxmox and switch native VLAN

### Traffic Separation

- **Management / Corosync** — 1GbE (dedicated)
- **Ceph cluster + public** — 10GbE (dedicated), 25GbE recommended
- **Migration** — 10GbE (recommended)
- **Guest** — depends on workload

**Critical rule:** Never combine Corosync traffic with high-bandwidth Ceph or mig