<!-- skill: Proxmox Homelab | version: 1.0.0 | description: ZFS install, LXC vs VM rule, backups, templates and clones | category: System & Productivity -->
## Instructions
- Install: Proxmox VE 8 ISO to bare metal, ZFS RAIDZ1/mirror if 2+ equal disks else LVM-thin single SSD; set static IP + gateway + DNS at install; `pve-no-subscription` repo for lab updates.
- LXC vs VM rule: LXC for stateless Linux services (nginx, *arr, docker-single-host caveat), VM for anything needing kernel modules, Windows, Docker-heavy, or untrusted images; privileged LXC only when bind-mount demands it.
- Storage layout: `local` (ISO/snippets), `local-lvm`/`local-zfs` (disks); keep 20% ZFS free (perf cliff); `zpool status` + `zfs list` weekly; enable `compression=lz4` on tank.
- Templates/clones: build gold Debian-12 LXC/VM → updates + qemu-guest-agent + SSH keys → `pct template`/`qm template` → clone linked for tests, full for keepers; never snowflake the gold.
- Backups (vzdump): schedule weekly full + daily snap for CTs, `mode: snapshot`, `compress: zstd`, retention 4; store on separate disk/NAS; PBS (Proxmox Backup Server) as LXC/VM when retention/dedup matters.
- Network: Linux bridge `vmbr0` (LAN), `vmbr1` (isolated/lab, no bridge-ports); virtio NICs, `firewall=1` per guest; MAC reservations in DHCP for servers.
- Resources: start small (1 vCPU/1GB LXC, 2 vCPU/4GB VM), ballooning on for VMs, `shares` for noisy neighbours; `pct top`/`pvesh` before adding silicon.
- Updates: host `apt update && apt full-upgrade` monthly (migrate guests first), guest unattended-upgrades; snapshot before kernel/pve updates; `pveversion -v` in change notes.
- Access: web UI `https://IP:8006`, SSH root + sudo user, TOTP 2FA on root; API token (`pveum`) for terraform/ansible, never root password in scripts.
- Monitoring: built-in summary + `pvestatd`, external Uptime Kuma LXC for alerts; SMART + `zpool scrub` monthly cron; UPS → NUT LXC with graceful shutdown.
- Pairs home-server: Proxmox is the floor, home-server skill services run as guests; one LXC per service so restores are surgical.
- Restore drills: quarterly `qmrestore`/`pct restore` to new ID, boot, curl health endpoint; untested backups are fiction.
## Examples
- Gold LXC: `pct create 9000 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst --hostname gold-deb12 --cores 2 --memory 2048 --rootfs local-zfs:8 --net0 name=eth0,bridge=vmbr0,ip=dhcp` → customize → `pct template 9000`.
- Clone: `pct clone 9000 101 --hostname arr --full 0` (linked test) or `--full 1` (keeper).
- Backup now: `vzdump 101 --mode snapshot --compress zstd --storage backups`.
- Scrub: `zpool scrub rpool` then `zpool status -v`.
## Workflows
1. Install: ISO → ZFS/LVM choice → static IP → updates → 2FA + users.
2. Gold: create → harden → agent/keys → template.
3. Service: clone → static IP → ansible/docker deploy → backup job include.
4. Maintain: monthly host patch (snapshot first) → scrub → prune backups.
5. Disaster: new disk → install → restore PBS/vzdump → verify boot + healthz.
## Templates
```bash
# post-install lab sources (/etc/apt/sources.list.d/pve-lab.list)
deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription
# then: apt update && apt full-upgrade -y && pveversion -v
# disable enterprise (no key): rm /etc/apt/sources.list.d/pve-enterprise.list
```
```bash
# backup schedule via UI or vzdump cron (/etc/cron.d/vzdump-lab)
# weekly full Sundays 02:00, keep 4
0 2 * * 0 root vzdump --all 1 --mode snapshot --compress zstd --storage backups --mailto admin@lan
# monthly scrub first Sunday 03:30
30 3 1-7 * 0 root [ "$(date +\%u)" = 7 ] && zpool scrub rpool
```
```bash
# LXC create fleet (linked clones from gold 9000)
for id in 101 102 103; do pct clone 9000 $id --full 0; done
pct start 101 && pct exec 101 -- hostname
# VM with agent: qm set <vmid> --agent enabled=1 && qm start <vmid>
```
```text
# guest sizing starter
# lxc: web 1c/1G/8G, arr 2c/2G/16G, kuma 1c/1G/8G
# vm: docker-host 4c/8G/64G, windows 4c/8G/80G, pbs 2c/4G/500G+datastore
```
## Tools
- Proxmox VE 8.x, Proxmox Backup Server (optional LXC), qemu-guest-agent, `pvesh`, `pct`/`qm`/`vzdump` CLI.
- Uptime Kuma LXC for alerts, NUT for UPS, ansible-playbooks skill for guest config.
## Advanced
- PCI passthrough (iGPU/NIC/HBA): enable IOMMU (`intel_iommu=on`), vfio modules, `qm set --hostpci0`; test reboot persistence; LXC GPU pass needs `lxc.cgroup2` + device mounts.
- ZFS: `zfs set compression=lz4 rpool`, `zfs snapshot rpool/data@pre-patch`, `zfs send/recv` to backup box; never fill past 80%.
- HA/cluster: 3 nodes + qdevice for true HA; 2-node without fencing is a split-brain trap — single node + good backups beats fake HA.
- Troubleshooting: guest no net → bridge/VLAN tag/firewall checkbox; slow ZFS → free space + `arcstat`, sync=disabled only for scratch; WebUI cert warn → ACME/LAN CA or tailscale; LXC docker fail → nesting + keyctl (`features: nesting=1,keyctl=1`).
## Documentation
- Proxmox VE Admin Guide (Help button in UI mirrors it).
- https://pve.proxmox.com/wiki/Main_Page
- https://pbs.proxmox.com/docs/ + `man pct`, `man qm`, `man vzdump`