claude-plugins/infraestrutura/skills/proxmox-setup/SKILL.md

---
name: proxmox-setup
description: Instalação completa de Proxmox VE 8.x em Hetzner - installimage, ZFS RAID-1, NAT networking, vSwitch. Use when user mentions "proxmox install", "setup proxmox", "proxmox hetzner", "new proxmox node".
author: Descomplicar® Crescimento Digital
version: 1.0.0
quality_score: 75
user_invocable: true
desk_task: 1712
allowed-tools: Task, Read, Bash
dependencies:
  - ssh-unified
  - notebooklm
---

# Proxmox Setup

Instalação completa e configuração de Proxmox VE 8.x em servidor dedicado Hetzner com ZFS RAID-1, networking NAT single-IP e optimizações.

## Quando Usar

- Instalar novo node Proxmox em servidor Hetzner
- Setup inicial com ZFS mirror NVMe
- Configurar networking NAT para single-IP
- Preparar node para clustering futuro
- Aplicar Hetzner-specific gotchas e optimizações

## Sintaxe

```bash
/proxmox-setup <server-ip> <hostname> [--zfs-pool rpool] [--arc-max 16G] [--vswitch]
```

## Exemplos

```bash
# Setup básico single-IP NAT
/proxmox-setup 138.201.45.67 cluster.descomplicar.pt

# Setup com vSwitch (MTU 1400)
/proxmox-setup 138.201.45.67 cluster.descomplicar.pt --vswitch

# Custom ZFS ARC (para 64GB RAM)
/proxmox-setup 138.201.45.67 pve-node1.descomplicar.pt --arc-max 8G
```

## Knowledge Sources (Consultar SEMPRE)

### NotebookLM Proxmox Research
```bash
mcp__notebooklm__notebook_query \
  notebook_id:"276ccdde-6b95-42a3-ad96-4e64d64c8d52" \
  query:"proxmox installation hetzner zfs networking"
```

### Hub Docs
- `/media/ealmeida/Dados/Hub/05-Projectos/Cluster Descomplicar/Research/Proxmox-VE/Guia-Definitivo-Proxmox-Hetzner.md`
- Módulo 1: Instalação (installimage, ZFS vs LVM, Kernel PVE)
- Módulo 2: Networking (NAT masquerading, vSwitch MTU 1400)

## Workflow Completo

### Fase 1: Pre-Installation Checks

**1.1 Verificar Rescue Mode**
```bash
# Via SSH MCP
mcp__ssh-unified__ssh_execute \
  server:"hetzner-rescue" \
  command:"uname -a && df -h"

# Expected: rescue kernel, /dev/md* present
```

**1.2 Consultar NotebookLM para Hardware Specs**
```bash
# Query: "hetzner installimage zfs raid configuration"
# Obter template correcto para specs do servidor
```

**1.3 Backup de Configuração Actual (se aplicável)**
```bash
ssh root@SERVER_IP "tar -czf /tmp/backup-configs.tar.gz /etc /root"
scp root@SERVER_IP:/tmp/backup-configs.tar.gz ~/backups/
```

### Fase 2: installimage com ZFS RAID-1

**2.1 Criar Template installimage**

Template base para 2x NVMe 1TB + HDD 16TB:
```bash
DRIVE1 /dev/nvme0n1
DRIVE2 /dev/nvme1n1
SWRAID 0
SWRAIDLEVEL 0
BOOTLOADER grub
HOSTNAME HOSTNAME_PLACEHOLDER
PART /boot ext3 1024M
PART lvm vg0 all

LV vg0 root / ext4 50G
LV vg0 swap swap swap 16G
LV vg0 tmp /tmp ext4 10G
LV vg0 home /home ext4 20G

IMAGE /root/images/Debian-bookworm-latest-amd64-base.tar.gz
```

**CRITICAL: Depois de boot, converter para ZFS:**

**2.2 Executar installimage**
```bash
# No Rescue Mode
installimage

# Seleccionar Debian 12 (Bookworm)
# Copiar template acima
# Salvar e confirmar
# Reboot automático
```

**2.3 Conversão para ZFS (Pós-Install)**

**IMPORTANTE:** installimage não suporta ZFS directamente. Workflow:
1. Instalar Debian 12 com LVM (installimage)
2. Boot em Debian
3. Instalar ZFS + Proxmox
4. Migrar para ZFS pool (ou aceitar LVM para root, ZFS para VMs)

**Opção A: ZFS para VMs apenas (RECOMENDADO para Hetzner)**
```bash
# Criar ZFS pool em NVMe para VMs
zpool create -f \
  -o ashift=12 \
  -o compression=lz4 \
  -o atime=off \
  rpool mirror /dev/nvme0n1p3 /dev/nvme1n1p3

# Criar datasets
zfs create rpool/vm-disks
zfs create rpool/ct-volumes
```

**Opção B: ZFS root (AVANÇADO - requer reinstall manual)**
- Não suportado por installimage
- Requer particionamento manual + debootstrap
- Consultar: https://pve.proxmox.com/wiki/ZFS_on_Linux

**Recomendação para Cluster Descomplicar:** Opção A (LVM root, ZFS para VMs)

### Fase 3: Proxmox VE 8.x Installation

**3.1 Configurar Repositórios Proxmox**
```bash
# Adicionar repo Proxmox
echo "deb [arch=amd64] http://download.proxmox.com/debian/pve bookworm pve-no-subscription" > /etc/apt/sources.list.d/pve-install-repo.list

# Adicionar key
wget https://enterprise.proxmox.com/debian/proxmox-release-bookworm.gpg -O /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg

# Update
apt update && apt full-upgrade
```

**3.2 Instalar Proxmox VE**
```bash
apt install proxmox-ve postfix open-iscsi chrony
```

**Configuração Postfix:**
- Seleccionar "Local only"
- System mail name: HOSTNAME

**3.3 Remover Kernel Debian (usar PVE kernel)**
```bash
# Verificar kernel actual
uname -r  # Should be pve kernel

# Remover kernel Debian se boot em PVE kernel
apt remove linux-image-amd64 'linux-image-6.1*'
update-grub
```

**3.4 Reboot em Proxmox Kernel**
```bash
reboot
```

### Fase 4: ZFS Tuning (128GB RAM)

**4.1 Configurar ARC Limits**
```bash
# ARC max 16GB (deixa 110GB para VMs)
# ARC min 4GB
echo "options zfs zfs_arc_max=17179869184" >> /etc/modprobe.d/zfs.conf
echo "options zfs zfs_arc_min=4294967296" >> /etc/modprobe.d/zfs.conf

# Aplicar
update-initramfs -u -k all
```

**4.2 Optimizar ZFS para NVMe**
```bash
# Verificar ashift (deve ser 12 para NVMe 4K sectors)
zdb -C rpool | grep ashift

# Activar compression LZ4 (se ainda não)
zfs set compression=lz4 rpool

# Disable atime (performance)
zfs set atime=off rpool

# Snapshot visibility
zfs set snapdir=hidden rpool
```

**4.3 Criar ZFS Datasets para PBS (se HDD 16TB)**
```bash
# Dataset para PBS datastore
zfs create rpool/pbs-datastore
zfs set mountpoint=/mnt/pbs-datastore rpool/pbs-datastore
zfs set compression=lz4 rpool/pbs-datastore
zfs set dedup=off rpool/pbs-datastore
```

### Fase 5: Networking NAT (Single-IP Hetzner)

**5.1 Configurar /etc/network/interfaces**

**Template para Single-IP NAT:**
```bash
auto lo
iface lo inet loopback

# Interface física (verificar nome com 'ip a')
auto eno1
iface eno1 inet static
        address   SERVER_IP/32
        gateway   GATEWAY_IP
        pointopoint GATEWAY_IP

# Bridge interna para VMs (NAT)
auto vmbr0
iface vmbr0 inet static
        address  10.10.10.1/24
        bridge-ports none
        bridge-stp off
        bridge-fd 0

        # NAT masquerading
        post-up   echo 1 > /proc/sys/net/ipv4/ip_forward
        post-up   iptables -t nat -A POSTROUTING -s '10.10.10.0/24' -o eno1 -j MASQUERADE
        post-down iptables -t nat -D POSTROUTING -s '10.10.10.0/24' -o eno1 -j MASQUERADE
```

**CRITICAL Hetzner Gotchas:**
- Gateway /32 point-to-point (não /24 ou /26)
- IP e gateway podem estar em subnets diferentes
- Verificar IP real e gateway no Hetzner Robot

**5.2 Aplicar Networking**
```bash
# Test config
ifup --no-act vmbr0

# Apply
systemctl restart networking

# Verificar
ip a
ping -c 3 8.8.8.8
```

**5.3 Port Forwarding (Opcional - para expor VMs)**
```bash
# Exemplo: Redirecionar porta 8080 host → porta 80 VM 10.10.10.100
iptables -t nat -A PREROUTING -i eno1 -p tcp --dport 8080 -j DNAT --to 10.10.10.100:80

# Persistir com iptables-persistent
apt install iptables-persistent
iptables-save > /etc/iptables/rules.v4
```

### Fase 6: vSwitch Configuration (Opcional)

**Se --vswitch flag presente:**

**6.1 Configurar VLAN no Robot Panel**
- Hetzner Robot → vSwitch → Create VLAN
- Anotar VLAN ID (ex: 4000)

**6.2 Adicionar ao /etc/network/interfaces**
```bash
# vSwitch interface (MTU 1400 OBRIGATÓRIO)
auto enp7s0.4000
iface enp7s0.4000 inet manual
        mtu 1400

# Bridge vSwitch
auto vmbr1
iface vmbr1 inet static
        address 10.0.0.1/24
        bridge-ports enp7s0.4000
        bridge-stp off
        bridge-fd 0
        mtu 1400
```

**CRITICAL:** MTU 1400 não negociável para vSwitch Hetzner.

### Fase 7: Proxmox Web UI + Storage

**7.1 Aceder Web UI**
```
https://SERVER_IP:8006

User: root
Password: (root password do servidor)
```

**7.2 Remover Enterprise Repo (se no-subscription)**
```bash
# Comentar enterprise repo
sed -i 's/^deb/#deb/' /etc/apt/sources.list.d/pve-enterprise.list

# Verificar
apt update
```

**7.3 Configurar Storage no Web UI**
- Datacenter → Storage → Add
- **Directory:** Local (já existe)
- **ZFS:** rpool/vm-disks (para VMs)
- **PBS:** Adicionar PBS server (se já instalado)

### Fase 8: Validation Checklist

**8.1 Verificações Técnicas**
```bash
# PVE version
pveversion -v

# ZFS status
zpool status
zpool list
zfs list

# Networking
ping -c 3 8.8.8.8
curl -I https://www.google.com

# Web UI
curl -k https://localhost:8006

# ARC stats
arc_summary | grep "ARC size"
```

**8.2 Security Hardening**
```bash
# SSH: Disable root password (usar keys)
sed -i 's/#PermitRootLogin yes/PermitRootLogin prohibit-password/' /etc/ssh/sshd_config
systemctl restart sshd

# Firewall básico (opcional - configurar via Web UI depois)
pve-firewall start
```

**8.3 Criar VM Teste**
```bash
# Via CLI (ou Web UI)
qm create 100 \
  --name test-vm \
  --memory 1024 \
  --cores 1 \
  --net0 virtio,bridge=vmbr0 \
  --ide2 local:iso/debian-12.iso,media=cdrom \
  --bootdisk scsi0 \
  --scsi0 rpool/vm-disks:10

# Start
qm start 100

# Verificar consegue aceder internet (NAT funcional)
```

## Output Summary

```
✅ Proxmox VE 8.x instalado: HOSTNAME

🖥️ Hardware:
   - CPU: (detect)
   - RAM: 128GB (ARC max 16GB, disponível 110GB para VMs)
   - Storage: 2x 1TB NVMe ZFS RAID-1 + 16TB HDD

💾 Storage:
   - ZFS pool: rpool (mirror)
   - Compression: LZ4 (ratio ~1.5x)
   - ARC: 4GB min, 16GB max
   - Datasets: vm-disks, ct-volumes, pbs-datastore

🌐 Networking:
   - Mode: NAT masquerading (single-IP)
   - Internal subnet: 10.10.10.0/24
   - Gateway: GATEWAY_IP (point-to-point)
   [Se vSwitch] vSwitch VLAN 4000: 10.0.0.0/24 (MTU 1400)

🔐 Access:
   - Web UI: https://SERVER_IP:8006
   - SSH: root@SERVER_IP (key only)
   - API: https://SERVER_IP:8006/api2/json

📋 Next Steps:
   1. Configurar firewall via Web UI (Datacenter → Firewall)
   2. Criar API token para Terraform (/pve-api-token)
   3. Setup PBS (/pbs-config)
   4. Criar Cloud-Init templates
   5. Migrar workloads (/vm-migration)
   6. [Futuro] Cluster formation (/proxmox-cluster)

⚠️ Hetzner Gotchas Applied:
   ✓ Gateway /32 point-to-point
   ✓ NAT masquerading (MAC filtering bypass)
   ✓ vSwitch MTU 1400 (se aplicável)
   ✓ ZFS ARC tuning
   ✓ PVE kernel (não Debian stock)

⏱️ Setup time: ~45min (vs 2h manual)
```

## Hetzner-Specific Gotchas (CRITICAL)

### 1. MAC Filtering
**Problema:** Bridged networking com MAC não registado = bloqueado
**Solução aplicada:** NAT masquerading (bypass MAC filtering)
**Alternativa:** Pedir virtual MAC no Robot panel (grátis)

### 2. Gateway Point-to-Point
**Problema:** Gateway fora da subnet do IP principal
**Solução:** `address IP/32` + `pointopoint GATEWAY` (não /24 ou /26)

### 3. vSwitch MTU 1400
**Problema:** vSwitch Hetzner requer MTU 1400 (não 1500 standard)
**Solução:** Forçar `mtu 1400` em vmbr1 e enp7s0.4000

### 4. ZFS vs LVM Trade-off
**Problema:** installimage não suporta ZFS root directo
**Solução:** LVM para root (compatibilidade), ZFS para VMs (performance)

### 5. Kernel PVE vs Debian
**Problema:** Kernel stock Debian não optimizado para virtualização
**Solução:** Instalar proxmox-ve + remover kernel Debian

## Troubleshooting

### Web UI não acessível
```bash
# Verificar serviço
systemctl status pveproxy

# Logs
journalctl -u pveproxy -f

# Firewall
iptables -L -n -v | grep 8006
```

### VMs sem internet (NAT)
```bash
# Verificar IP forwarding
cat /proc/sys/net/ipv4/ip_forward  # Should be 1

# Verificar iptables NAT
iptables -t nat -L -n -v

# Re-aplicar regras
ifdown vmbr0 && ifup vmbr0
```

### ZFS ARC não limita
```bash
# Verificar configs
cat /sys/module/zfs/parameters/zfs_arc_max

# Re-aplicar
modprobe -r zfs
modprobe zfs
```

### vSwitch MTU issues
```bash
# Forçar MTU em todas interfaces
ip link set enp7s0.4000 mtu 1400
ip link set vmbr1 mtu 1400

# Test
ping -M do -s 1372 10.0.0.2  # 1372 = 1400 - 28 (headers)
```

## References

- **NotebookLM:** 276ccdde-6b95-42a3-ad96-4e64d64c8d52 (150+ fontes)
- **Guia Definitivo:** Hub/05-Projectos/Cluster Descomplicar/Research/Proxmox-VE/Guia-Definitivo-Proxmox-Hetzner.md
- **Proxmox Docs:** https://pve.proxmox.com/pve-docs/pve-admin-guide.html
- **Hetzner Docs:** https://docs.hetzner.com/robot/dedicated-server/

---

**Versão:** 1.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-14

## Metadata (Desk CRM Task #1712)

```
Projeto: Cluster Proxmox Descomplicar (#65)
Tarefa: Migração Infraestrutura para Cluster Proxmox HA (#1712)
Milestone: TBD
Tags: proxmox, pve, hetzner, zfs, networking, instalacao
Status: Research → Implementation
```

---

**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/

---

## Quando NÃO Usar

- Para servidores non-Hetzner (diferentes gotchas de networking)
- Para Proxmox já instalado (usar outras skills de config)
- Para troubleshooting (criar skill específica)