Proxmox VE

Guia prático e completo para subir um host de virtualização com Proxmox VE 8.x — pensando em quem já tem familiaridade com Debian, KVM e Linux, mas quer um passo a passo opinativo para montar um laboratório “de gente grande”: VMs, LXC, ZFS, snapshots, backups, PCIe passthrough e cluster.

Audiência alvo: dev sênior, com servidor Debian já em produção, planejando rodar Proxmox em um mini-PC ou desktop reaproveitado para hospedar VMs Linux variadas, containers LXC e (provavelmente) TrueNAS como VM com passthrough de HBA.

Sumário:

1. Visão geral
2. Arquitetura
3. Pré-requisitos de hardware
4. Instalação
5. Pós-instalação
6. Storage
7. Networking
8. Criando uma VM
9. Cloud-init template
10. Containers LXC
11. Snapshots e backups
12. PCIe passthrough
13. Cluster (multi-node)
14. Acesso e segurança
15. Monitoramento
16. Troubleshooting
17. Referências

1. Visão geral

Proxmox VE (Virtual Environment) é uma distribuição Linux baseada em Debian que entrega uma plataforma de virtualização “Type-1-like” pronta para produção, com:

• KVM/QEMU — virtualização completa (VMs com SO próprio, BIOS/UEFI, hardware emulado).
• LXC — containers de sistema (kernel compartilhado, overhead mínimo, isolamento por namespaces/cgroups).
• ZFS on Linux — filesystem/volume manager nativamente integrado (boot em mirror, snapshots, send/receive, compressão).
• Ceph — storage distribuído opcional para clusters (RBD, CephFS).
• Web UI em https://IP:8006 — gerenciamento gráfico de tudo (VMs, LXCs, storage, rede, backup, cluster, ACME, MFA).
• Cluster nativo — Corosync + Proxmox Cluster Filesystem (pmxcfs) sincroniza configuração entre nós; HA com fencing.
• CLI poderosa — qm, pct, pvesh, pvesm, pvecm, vzdump.

Free vs Subscription

O Proxmox VE é 100% open source (AGPLv3) e gratuito. A “subscription” paga dá:

• Acesso ao repositório enterprise (mais lento, mais testado).
• Suporte técnico oficial via portal.
• Sem o banner “No valid subscription”.

Para uso em laboratório, o pve-no-subscription é o caminho normal — recebe os mesmos pacotes da enterprise, só que mais cedo (já validados em testing). Estável o suficiente para LAN interna e laboratórios.

Comparação rápida com alternativas

Em 2024–2026, com a Broadcom matando o ESXi free, Proxmox virou o padrão de fato para laboratórios e pequenas empresas. XCP-ng é viável se você prefere Xen, e Unraid continua imbatível em “NAS doméstico com Apps” mas é fraco em cluster/HA.

2. Arquitetura

Visão de um host único

flowchart TB
    subgraph HW["Hardware"]
        CPU["CPU<br/>VT-x/AMD-V + VT-d/AMD-Vi"]
        RAM["RAM ECC (ideal)<br/>min 8 GB, recomendado 32+ GB"]
        NIC["NIC 1 GbE (mín)<br/>idealmente 2x p/ bond/cluster"]
        NVME["NVMe/SSD boot<br/>(2x p/ ZFS mirror)"]
        HDD["HDDs dados<br/>(passthrough p/ TrueNAS<br/>ou pool ZFS local)"]
        UPS["UPS (NUT)"]
    end

    subgraph HOST["Proxmox VE Host (Debian 12 Bookworm)"]
        KERNEL["Kernel Proxmox (6.8+)<br/>KVM + LXC + ZFS"]
        PVED["pvedaemon / pveproxy<br/>pmxcfs / pve-cluster"]
        STORAGE["Storage layer<br/>local-zfs / local-lvm / NFS / Ceph"]
        NET["Bridge vmbr0/1/2<br/>VLAN aware"]
    end

    subgraph VMS["VMs (KVM)"]
        VM1["VM Debian<br/>servicos gerais"]
        VM2["VM TrueNAS Scale<br/>HBA via PCIe passthrough"]
        VM3["VM Windows<br/>GPU passthrough (opcional)"]
    end

    subgraph LXCS["LXC Containers"]
        CT1["CT Pi-hole<br/>unprivileged"]
        CT2["CT Nginx Proxy Manager"]
        CT3["CT Docker host<br/>(nesting=1)"]
    end

    HW --> HOST
    HOST --> VMS
    HOST --> LXCS

Cluster opcional (3+ nodes)

flowchart LR
    subgraph CLUSTER["Cluster Proxmox"]
        N1["pve01<br/>192.168.1.11"]
        N2["pve02<br/>192.168.1.12"]
        N3["pve03<br/>192.168.1.13"]
    end

    COROSYNC["Corosync ring(s)<br/>UDP 5405-5412<br/>VLAN dedicada idealmente"]
    PMXCFS["pmxcfs<br/>/etc/pve sincronizado"]
    HA["HA Manager<br/>fencing + restart"]

    N1 <--> COROSYNC
    N2 <--> COROSYNC
    N3 <--> COROSYNC
    COROSYNC --> PMXCFS
    PMXCFS --> HA

    SHARED["Shared storage<br/>(Ceph / NFS / iSCSI)<br/>obrigatorio p/ HA real"]
    HA --> SHARED

Para 2 nodes, adicione um QDevice (um Raspberry Pi rodando corosync-qnetd resolve) — sem 3º voto, qualquer falha de rede entre os dois leva a split-brain.

3. Pré-requisitos de hardware

Mínimos x recomendados

CPU: virtualização e IOMMU

Você precisa de duas extensões distintas:

• VT-x (Intel) / AMD-V — virtualização básica. Sem isto, KVM nem inicia.
• VT-d (Intel) / AMD-Vi (IOMMU) — necessária para PCIe passthrough (passar GPU, HBA, NIC para uma VM).

Confira no BIOS/UEFI antes de comprar: muitos chips Intel “F” (sem iGPU) ou consumer antigos têm VT-x mas não VT-d. Em CPUs AMD modernas (Ryzen 3000+, Epyc), os dois vêm habilitados; em Intel, geralmente é “Intel VT-d” no BIOS, separado de “Intel Virtualization Technology”.

Verifique depois de instalado:

# Intel
grep -E 'vmx|svm' /proc/cpuinfo
dmesg | grep -i -e DMAR -e IOMMU

# AMD
dmesg | grep -i -e AMD-Vi -e IOMMU

IOMMU groups

PCIe passthrough exige que o dispositivo a ser passado esteja em um IOMMU group isolado dos componentes do host. Placas-mãe consumer baratas costumam ter “tudo no mesmo grupo”, o que inviabiliza passthrough sem patch ACS (ACS override patch — funciona, mas é gambiarra).

Boas escolhas de mini-PC para laboratório:

• Mini-PCs (silenciosos, baixo consumo): Beelink/Minisforum com Ryzen 7 5700U/5800U/7735HS, ou Intel N100/N305 (esses últimos sem ECC e com IOMMU sofrível).
• Workstation barata: Dell Optiplex/Precision com Xeon E (ECC + VT-d).
• Servidor “real”: HPE MicroServer Gen10+, Supermicro X10/X11.

Storage layout sugerido

2x NVMe 500 GB        -> ZFS mirror (rpool) — boot + VMs/LXC pequenos
2x SSD 1 TB           -> ZFS mirror (tank-fast) — VMs/LXC ativos
4x HDD 4 TB           -> ZFS raidz2 ou passthrough p/ TrueNAS
1x SSD 250 GB (cache) -> L2ARC do pool de HDDs (opcional)

Rede

1 NIC gigabit já roda. Mas se planeja cluster, separe management de corosync de VM traffic. Para 1 host só:

• vmbr0 — LAN principal, NIC física (DHCP do router ou IP estático).
• vmbr1 — VLAN trunk se o switch suportar (rede gerenciada).
• vmbr2 — bridge interna (sem NIC) para rede privada entre VMs.

4. Instalação

4.1 Download da ISO

Pegue a ISO oficial em https://www.proxmox.com/en/downloads/proxmox-virtual-environment/iso. Para PVE 8.x, é a “Proxmox VE 8.4 ISO Installer” (ou versão corrente da branch 8.x).

Confira o checksum SHA-256 publicado ao lado do link:

sha256sum proxmox-ve_8.4-1.iso
# compare com o valor da página

4.2 Gravar em USB

Linux/macOS (dd):

# Liste discos antes
lsblk

# Atenção: of=/dev/sdX -- substitua pelo pendrive correto
sudo dd if=proxmox-ve_8.4-1.iso of=/dev/sdX bs=1M status=progress conv=fsync
sync

Windows / multi-plataforma: balenaEtcher, Rufus (modo DD), Ventoy.

Não use Rufus em modo ISO/UEFI “Windows To Go” — o instalador Proxmox espera o layout bit-a-bit do dd. Em Rufus, escolha DD image quando perguntar.

4.3 Boot e instalador

1. No BIOS/UEFI, habilite Virtualization (VT-x/AMD-V), VT-d/AMD-Vi (IOMMU), Above 4G Decoding e Secure Boot OFF (pode interferir em drivers VFIO).
2. Boot pelo USB → escolha Install Proxmox VE (Graphical).
3. Aceite a EULA.
4. Target Harddisk → clique em Options:
   • Filesystem: zfs (RAID1) se tiver 2 discos iguais (mirror — recomendado para boot resiliente).
   • ashift: 12 (4K) é o default seguro; use 13 para NVMe modernos se souber o que está fazendo.
   • compress: lz4 (padrão, ótimo trade-off).
   • hdsize: se quiser deixar espaço livre para outro pool depois, reduza aqui.
5. Country/Timezone/Keyboard — Brazil / America/Sao_Paulo / pt-br.
6. Password + Email — senha forte para root; email é usado para alertas de SMART, backup, etc.
7. Network:
   • Management Interface: sua NIC (enp2s0, eno1…).
   • Hostname (FQDN): pve01.lab.example.com (use um TLD interno, evite .local por causa de mDNS).
   • IP Address (CIDR): 192.168.1.11/24 (estático — fixe no DHCP do roteador também).
   • Gateway: 192.168.1.1.
   • DNS Server: 192.168.1.1 ou 1.1.1.1.
8. Confirme o sumário, instale, reboot, remova o USB.

4.4 Primeiro acesso

https://192.168.1.11:8006

Aceite o certificado autoassinado, login root + senha definida, Realm = Linux PAM standard authentication, idioma “Portuguese (Brazil)” se preferir.

5. Pós-instalação

5.1 Repositórios APT

A instalação default adiciona o repositório enterprise, que exige subscription. Sem subscription, apt update falha com 401. Troque para no-subscription.

# Desativar enterprise (PVE 8 / Debian Bookworm)
sed -i 's/^deb/# deb/' /etc/apt/sources.list.d/pve-enterprise.list

# Desativar Ceph enterprise se nao usar Ceph
sed -i 's/^deb/# deb/' /etc/apt/sources.list.d/ceph.list 2>/dev/null || true

# Adicionar no-subscription
cat > /etc/apt/sources.list.d/pve-no-subscription.list <<'EOF'
deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription
EOF

# Se for usar Ceph (squid e a serie atual estavel)
cat > /etc/apt/sources.list.d/ceph-no-subscription.list <<'EOF'
deb http://download.proxmox.com/debian/ceph-squid bookworm no-subscription
EOF

apt update
apt full-upgrade -y
reboot

Em PVE 9 / Debian Trixie, o formato muda para .sources (deb822). Para PVE 8 (Bookworm), o .list clássico ainda é o padrão.

5.2 Banner “No valid subscription”

Toda vez que você loga na web UI sem subscription, aparece um diálogo. Em ambiente de laboratório, dá para remover via patch no JS. A forma menos invasiva é usar o script da comunidade Proxmox VE Helper-Scripts (community-scripts), que detecta versão e atualiza automaticamente:

bash <(curl -s https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/post-pve-install.sh)

Esse script unifica: troca repos, remove banner, ajusta apt, oferece habilitar HA mesmo em single-node etc. Leia antes de rodar.

Patch manual (caso prefira):

sed -Ezi "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

(Após apt full-upgrade do proxmox-widget-toolkit, o patch precisa ser reaplicado — daí o script é mais prático.)

5.3 Timezone, NTP, hostname

timedatectl set-timezone America/Sao_Paulo

# Proxmox usa systemd-timesyncd por padrao; trocar por chrony e opcional
apt install -y chrony
systemctl disable --now systemd-timesyncd
systemctl enable --now chrony
chronyc tracking

# Hostname / /etc/hosts (precisa ter FQDN resolvendo p/ IP da NIC management)
hostnamectl set-hostname pve01
grep pve01 /etc/hosts
# Deve conter: 192.168.1.11 pve01.lab.example.com pve01

5.4 Pacotes úteis

apt install -y \
    htop iotop iftop tmux vim curl wget rsync \
    lm-sensors smartmontools nvme-cli \
    ifupdown2 ethtool \
    zfsutils-linux \
    fail2ban \
    qemu-guest-agent

ifupdown2 permite “Apply configuration” pela web UI sem reboot ao editar redes.

5.5 Atualização do microcódigo CPU

# Intel
apt install -y intel-microcode
# AMD (em geral ja vem)
apt install -y amd64-microcode
update-initramfs -u -k all
reboot

6. Storage

6.1 Conceitos de storage no Proxmox

O Proxmox abstrai storages e cada um aceita tipos específicos de conteúdo:

Tipos de content que você marca por storage: Disk image, ISO image, Container template, VZDump backup file, Container, Snippets.

6.2 Storage default

Após instalar com ZFS RAID1, o Proxmox já cria:

• local (tipo dir, em /var/lib/vz) — ISO, backup, template.
• local-zfs (tipo zfspool, em rpool/data) — disk images e containers.

Veja o arquivo:

cat /etc/pve/storage.cfg

dir: local
    path /var/lib/vz
    content iso,vztmpl,backup
    shared 0

zfspool: local-zfs
    pool rpool/data
    content rootdir,images
    sparse 1

6.3 Criar um pool ZFS adicional para dados

Cenário: 2 SSDs adicionais em mirror para VMs “quentes”.

# Identificar discos por by-id (recomendado em vez de /dev/sdX)
ls -l /dev/disk/by-id/ | grep -v part

# Criar pool
zpool create -o ashift=12 \
    -O compression=lz4 \
    -O atime=off \
    -O xattr=sa \
    tank mirror \
    /dev/disk/by-id/ata-Samsung_SSD_870_EVO_1TB_S1XXXXXXXA \
    /dev/disk/by-id/ata-Samsung_SSD_870_EVO_1TB_S1XXXXXXXB

# Verificar
zpool status tank
zfs list

# Criar dataset dedicado para imagens de VM
zfs create tank/vm

Adicione ao Proxmox (web UI → Datacenter → Storage → Add → ZFS) ou via CLI:

pvesm add zfspool tank-vm \
    --pool tank/vm \
    --content rootdir,images \
    --sparse 1

/etc/pve/storage.cfg deve então conter:

zfspool: tank-vm
    pool tank/vm
    content images,rootdir
    sparse 1

6.4 Boas práticas ZFS no Proxmox

• ashift=12 salvo se discos forem 8K nativos.

• compression=lz4 sempre ligado — overhead nulo, ganho real.

• atime=off evita writes desnecessários em reads.

• ARC: por padrão o ZFS no Linux usa até 50% da RAM. Em laboratório, limite:

  # 4 GB max
  echo "options zfs zfs_arc_max=4294967296" > /etc/modprobe.d/zfs.conf
  update-initramfs -u

• SWAP em ZFS: evite. Se precisar de swap, use uma partição dedicada fora do pool.

• TRIM mensal:

  systemctl enable --now zfs-trim-monthly.timer 2>/dev/null || \
      (echo "0 3 1 * * zpool trim rpool && zpool trim tank" | crontab -)

• Scrub mensal já vem habilitado pelo zfs-scrub timer; confirme:

  systemctl list-timers | grep zfs

6.5 Conteúdo por storage (regra prática)

• local (dir em rpool) — só ISO + Backup + Template. Tem pouco espaço, então não jogue VM nele.
• local-zfs — VMs e LXC pequenos do “sistema”.
• tank-vm — VMs de trabalho.
• NAS NFS/CIFS — backups e ISOs grandes.
• PBS (se tiver) — backups deduplicados.

7. Networking

7.1 Bridge default vmbr0

A instalação cria vmbr0 com a NIC física como bridge-ports, e o IP do host fica nessa bridge (não na NIC). Isso é o equivalente a um “switch virtual” — VMs e LXCs conectados em vmbr0 ficam na mesma LAN do host.

Arquivo: /etc/network/interfaces — não edite à mão se possível, use a web UI (com ifupdown2 permite “Apply” sem reboot).

Exemplo típico:

auto lo
iface lo inet loopback

iface enp2s0 inet manual

auto vmbr0
iface vmbr0 inet static
    address 192.168.1.11/24
    gateway 192.168.1.1
    bridge-ports enp2s0
    bridge-stp off
    bridge-fd 0
    bridge-vlan-aware yes
    bridge-vids 2-4094

A flag bridge-vlan-aware yes transforma vmbr0 num trunk, permitindo VMs com tag VLAN diferente (ver 7.3).

7.2 Bridges adicionais

Cenários comuns:

• vmbr1 em outra NIC física, ligada a um switch isolado (segregação de tráfego).
• vmbr2 sem NIC física — rede interna entre VMs (“host-only”), útil para um lab isolado.

# Rede interna isolada (sem porta fisica)
auto vmbr2
iface vmbr2 inet static
    address 10.10.99.1/24
    bridge-ports none
    bridge-stp off
    bridge-fd 0

Habilite NAT/masquerade se quiser que VMs em vmbr2 saiam para a internet via host:

    post-up   iptables -t nat -A POSTROUTING -s 10.10.99.0/24 -o vmbr0 -j MASQUERADE
    post-down iptables -t nat -D POSTROUTING -s 10.10.99.0/24 -o vmbr0 -j MASQUERADE

E habilite forwarding:

sed -i 's/^#net.ipv4.ip_forward=1/net.ipv4.ip_forward=1/' /etc/sysctl.conf
sysctl -p

7.3 VLAN tagging em VMs

Com bridge-vlan-aware yes em vmbr0, na configuração da NIC da VM (web UI → VM → Hardware → Network Device → VLAN Tag) você só precisa colocar o ID da VLAN. O host injeta a tag, sem precisar de subinterfaces tipo vmbr0.20.

7.4 Bond (LACP) para 2 NICs

iface eno1 inet manual
iface eno2 inet manual

auto bond0
iface bond0 inet manual
    bond-slaves eno1 eno2
    bond-miimon 100
    bond-mode 802.3ad
    bond-xmit-hash-policy layer2+3

auto vmbr0
iface vmbr0 inet static
    address 192.168.1.11/24
    gateway 192.168.1.1
    bridge-ports bond0
    bridge-stp off
    bridge-fd 0
    bridge-vlan-aware yes
    bridge-vids 2-4094

Requer switch com LACP configurado nas duas portas.

7.5 OpenvSwitch (alternativa)

Para topologias avançadas (GRE, VXLAN, OpenFlow, QoS por porta), instale openvswitch-switch e use ovs_type OVSBridge no interfaces. Para laboratório básico, Linux bridge basta e é mais simples.

8. Criando uma VM

Vamos criar uma VM Debian 13 “manual” pela UI. (Para clones rápidos, ver seção 9.)

8.1 Upload da ISO

Web UI → node pve01 → local → ISO Images → Upload (ou Download from URL):

https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-13.0.0-amd64-netinst.iso

8.2 Wizard “Create VM”

Botão azul no canto superior direito. Aba por aba:

General

• Node: pve01
• VM ID: 100 (ranges sugeridos: 100–199 servers, 200–299 desktops, 9000+ templates)
• Name: srv-tools
• Resource Pool: (opcional)

OS

• ISO image: local:iso/debian-13.0.0-amd64-netinst.iso
• Type: Linux, Version: 6.x - 2.6 Kernel

System

• Graphic card: Default
• Machine: q35 (PCIe nativo, recomendado para SO modernos)
• BIOS: OVMF (UEFI) + adicione um EFI Disk (em local-zfs, sem secure boot por enquanto)
• SCSI Controller: VirtIO SCSI single
• Qemu Agent: marcar
• TPM: marcar se for instalar Windows 11

Disks

• Bus/Device: SCSI 0
• Storage: local-zfs ou tank-vm
• Disk size: 32 GiB
• Cache: Default (No cache)
• Discard: marcar (TRIM/UNMAP)
• IO thread: marcar (paraleliza I/O)
• SSD emulation: marcar (se backing é SSD/NVMe — habilita TRIM no SO da VM)

CPU

• Sockets: 1
• Cores: 2 (ou mais; nunca aloque mais do que cores físicas totais sem oversubscription consciente)
• Type: host (passa flags reais — melhor performance; só evite se for migrar entre CPUs muito diferentes)

Memory

• Memory: 4096 MB
• Minimum memory: 2048 MB (habilita ballooning — host pode reclamar RAM)
• Ballooning: marcar (precisa qemu-guest-agent + driver virtio-balloon dentro)

Network

• Bridge: vmbr0
• Model: VirtIO (paravirtualized)
• VLAN tag: vazio (ou ID se for VLAN)
• Firewall: ligado por default (não bloqueia nada até você criar regras)

Confirm

• “Start after created”: opcional. Finalize.

8.3 Instalar SO

• Abra Console (noVNC).

• Instale Debian normalmente.

• Após primeiro boot, dentro da VM:

  apt update && apt install -y qemu-guest-agent
  systemctl enable --now qemu-guest-agent

• Volte na web UI → VM → Hardware → confirme que “QEMU Guest Agent” = Enabled, e em Options → QEMU Guest Agent → Edit → Use QEMU Guest Agent = Yes.

A partir daí o Proxmox consegue: shutdown gracioso, congelar FS antes de snapshot/backup, mostrar IPs reais na aba Summary.

8.4 Atalhos de CLI (qm)

qm list                            # listar VMs
qm start 100                       # iniciar
qm shutdown 100                    # shutdown via agent
qm stop 100                        # forcado (power off)
qm config 100                      # ver config
qm set 100 --memory 8192           # editar
qm resize 100 scsi0 +20G           # crescer disco
qm migrate 100 pve02 --online      # live migrate (cluster)
qm destroy 100 --purge             # remover (purge limpa firewall/backup refs)

9. Cloud-init template

Em vez de instalar SO toda vez, baixe a imagem generic cloud da distro, transforme em template e clone com cloud-init para injetar hostname, IP, usuário e SSH key. Provisionar uma VM nova vira ~10 segundos.

9.1 Baixar imagem cloud

mkdir -p /var/lib/vz/template/cloud
cd /var/lib/vz/template/cloud

# Debian 13 genericcloud (substitua pelo link mais novo no momento)
wget https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2

# Ubuntu 24.04 LTS, alternativa
# wget https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img

9.2 Criar template (VM 9000)

# 1. Criar shell de VM
qm create 9000 \
    --name debian-13-tpl \
    --memory 2048 \
    --cores 2 \
    --cpu host \
    --net0 virtio,bridge=vmbr0 \
    --scsihw virtio-scsi-single \
    --machine q35 \
    --bios ovmf \
    --agent enabled=1

# 2. EFI disk
qm set 9000 --efidisk0 local-zfs:0,efitype=4m,pre-enrolled-keys=0

# 3. Importar a qcow2 como scsi0
qm set 9000 --scsi0 local-zfs:0,import-from=/var/lib/vz/template/cloud/debian-13-genericcloud-amd64.qcow2,discard=on,iothread=1,ssd=1

# 4. Cloud-init drive
qm set 9000 --ide2 local-zfs:cloudinit

# 5. Boot order e console serial (cloud images esperam serial)
qm set 9000 --boot order=scsi0
qm set 9000 --serial0 socket --vga serial0

# 6. Defaults cloud-init (pode sobrescrever no clone)
qm set 9000 --ciuser admin
qm set 9000 --sshkey ~/.ssh/id_ed25519.pub
qm set 9000 --ipconfig0 ip=dhcp
qm set 9000 --nameserver 192.168.1.1
qm set 9000 --searchdomain lab.example.com

# 7. Redimensionar disco para tamanho util (imagem cloud vem com ~2 GB)
qm resize 9000 scsi0 +20G

# 8. Converter em template
qm template 9000

9.3 Clonar e provisionar

Linked clone (rápido, depende do template — útil em lab):

qm clone 9000 101 --name srv-api --full 0
qm set 101 --ipconfig0 ip=192.168.1.21/24,gw=192.168.1.1
qm set 101 --memory 4096 --cores 2
qm start 101

Full clone (independente — recomendado para produção doméstica):

qm clone 9000 102 --name srv-db --full 1
qm set 102 --ipconfig0 ip=192.168.1.22/24,gw=192.168.1.1
qm set 102 --memory 8192 --cores 4
qm start 102

Após boot, a VM já está acessível via SSH com sua chave, sem precisar abrir console.

9.4 Snippets (cloud-init customizado)

Para user-data mais elaborado (instalar pacotes, rodar scripts), habilite content snippets em algum storage (local por padrão aceita) e crie:

# /var/lib/vz/snippets/srv-api-userdata.yaml
#cloud-config
hostname: srv-api
manage_etc_hosts: true
package_update: true
package_upgrade: true
packages:
  - htop
  - tmux
  - vim
  - curl
  - qemu-guest-agent
users:
  - name: admin
    groups: sudo
    shell: /bin/bash
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - ssh-ed25519 AAAA... admin@workstation
runcmd:
  - systemctl enable --now qemu-guest-agent

E aplique:

qm set 101 --cicustom "user=local:snippets/srv-api-userdata.yaml"
qm cloudinit update 101
qm reboot 101

10. Containers LXC

10.1 Quando preferir LXC vs VM

10.2 Baixar template

Web UI → node → local → CT Templates → Templates → escolha debian-13-standard, download.

Via CLI:

pveam update
pveam available | grep debian-13
pveam download local debian-13-standard_13.0-1_amd64.tar.zst

10.3 Criar CT (UI: “Create CT”)

General

• CT ID: 200
• Hostname: ct-pihole
• Password: senha root
• SSH public key: cole sua chave

Template

• Storage: local
• Template: debian-13-standard_...

Disks

• Storage: local-zfs
• Size: 4 GiB

CPU

• Cores: 1

Memory

• RAM: 512 MiB
• Swap: 512 MiB

Network

• Name: eth0
• Bridge: vmbr0
• IPv4: static, 192.168.1.53/24, gw 192.168.1.1

DNS

• (deixar default usa do host)

Confirm

• Marque “Start after created”.

10.4 Unprivileged vs Privileged

• Unprivileged (default — recomendado): UID 0 dentro do container mapeia para um UID alto (100000+) no host. Bem mais seguro. Algumas coisas chatas: mounts manuais, --privileged no docker dentro etc.
• Privileged: UID 0 do container = root do host. Use só se precisar e souber a implicação.

10.5 Features (nesting, keyctl, fuse, mount)

Para rodar Docker dentro de um LXC unprivileged, na criação marque (ou edite depois):

• nesting=1 — permite cgroups aninhados.
• keyctl=1 — necessário para o keyring que algumas distros usam.

CLI:

pct set 200 -features nesting=1,keyctl=1
pct reboot 200

Outras features:

• mount=nfs;cifs — montar NFS/CIFS de dentro do CT.
• fuse=1 — montar com FUSE (sshfs etc.).

10.6 Atalhos pct

pct list
pct start 200
pct enter 200            # shell dentro do CT
pct exec 200 -- apt update
pct stop 200
pct destroy 200 --purge
pct snapshot 200 antes-do-upgrade
pct rollback 200 antes-do-upgrade

10.7 Caso prático: Pi-hole em LXC unprivileged

pct enter 200
apt update && apt -y install curl
curl -sSL https://install.pi-hole.net | bash
# (escolha eth0, IP estatico ja configurado, upstream 1.1.1.1)

Aponte o DHCP do roteador para usar 192.168.1.53 como DNS e pronto — DNS sinkhole na LAN inteira em ~5 min e ~50 MB de RAM.

11. Snapshots e backups

11.1 Snapshots

Snapshot = instantâneo point-in-time. Depende do storage suportar a operação:

UI: VM/CT → Snapshots → Take Snapshot (nome + descrição; marque “Include RAM” se quiser snapshot de estado vivo).

CLI:

qm snapshot 100 antes-upgrade --description "antes do apt upgrade" --vmstate 0
qm listsnapshot 100
qm rollback 100 antes-upgrade
qm delsnapshot 100 antes-upgrade

Snapshots não substituem backup. Se o pool morre, vão junto.

11.2 Backups com vzdump

vzdump é a ferramenta nativa. Tipos (modos):

• snapshot (recomendado): tira snapshot, copia dele, libera. VM continua rodando. Exige storage que suporte snapshot.
• suspend: pausa a VM brevemente para snapshot consistente, retoma. Trade-off entre downtime mínimo e consistência.
• stop: desliga a VM, copia, religa. Maior downtime, 100% consistente.

Compressão: zstd (default, melhor relação CPU/ratio), gzip, lzo.

CLI:

vzdump 100 --storage local --mode snapshot --compress zstd --notes-template "{{guestname}}"

Schedule pela UI: Datacenter → Backup → Add.

• Storage de destino: NFS ou PBS.
• Schedule: 02:00 diário, ou mon..fri 02:00.
• Selection: Include all ou IDs específicos.
• Mode: snapshot.
• Compression: zstd.
• Prune (retenção): keep-daily=7, keep-weekly=4, keep-monthly=6.
• Notification mode: Notification system (e-mail).

11.3 Proxmox Backup Server (PBS)

PBS é uma máquina (VM, container ou outro mini-PC) rodando o produto separado da Proxmox, com:

• Deduplicação (chunks de ~4 MB).
• Incremental forever após o full inicial.
• Verify periódico (lê de volta e confere hash).
• GC automatizado.
• Sync remoto (replicar repo para um segundo PBS off-site).

Adicionar PBS como storage no PVE: Datacenter → Storage → Add → Proxmox Backup Server com IP, datastore, fingerprint, usuário (backup@pbs) e senha/API token. Depois é só apontar o job de backup para esse storage.

11.4 Restore

UI: vá no backup → Restore, escolha VM ID destino e storage. CLI:

qmrestore /var/lib/vz/dump/vzdump-qemu-100-2026_05_11-02_00_00.vma.zst 110 --storage local-zfs

Sempre teste restore em VM ID alternativo uma vez por mês. Backup que nunca foi restaurado é uma teoria.

12. PCIe passthrough

Caso de uso típico: passar uma HBA SAS LSI ou várias portas SATA para uma VM TrueNAS Scale, para o TrueNAS controlar os discos diretamente e fazer ZFS por cima sem virtualização de I/O.

12.1 Habilitar IOMMU no boot

Edite /etc/default/grub:

# Intel
GRUB_CMDLINE_LINUX_DEFAULT="quiet intel_iommu=on iommu=pt"

# AMD (kernels 6.8+ ja vem ligado, mas explicito nao machuca)
GRUB_CMDLINE_LINUX_DEFAULT="quiet amd_iommu=on iommu=pt"

Atualize e reinicie:

update-grub
reboot

Se você instalou Proxmox em ZFS RAID1, o bootloader é systemd-boot (não GRUB). Edite então /etc/kernel/cmdline:

root=ZFS=rpool/ROOT/pve-1 boot=zfs quiet intel_iommu=on iommu=pt

E aplique:

proxmox-boot-tool refresh

12.2 Carregar módulos VFIO

cat >> /etc/modules <<'EOF'
vfio
vfio_iommu_type1
vfio_pci
EOF

update-initramfs -u -k all
reboot

12.3 Verificar IOMMU

dmesg | grep -i -e DMAR -e IOMMU -e AMD-Vi
# Deve haver linhas tipo "DMAR: IOMMU enabled" (Intel) ou "AMD-Vi: AMD IOMMUv2 functionality"

# Listar grupos IOMMU (caminho oficial via API)
pvesh get /nodes/pve01/hardware/pci --pci-class-blacklist ""

# Ou via shell direto
for d in /sys/kernel/iommu_groups/*/devices/*; do
  n=${d#*/iommu_groups/*}; n=${n%%/*}
  printf 'IOMMU Group %s: %s\n' "$n" "$(lspci -nns "${d##*/}")"
done | sort -V

Cada device a ser passado precisa estar em um grupo isolado das peças do host (NIC, NVMe boot etc.). Se uma HBA está no mesmo grupo do controlador NVMe, passthrough vai derrubar o host quando você der start na VM.

12.4 Blacklist do driver do host

Se o host estiver usando o device (ex: GPU NVIDIA com nouveau), desvincule:

# Ver o que esta vinculado
lspci -k -s 01:00.0

# Blacklist do driver original
cat > /etc/modprobe.d/blacklist-vfio.conf <<'EOF'
blacklist nouveau
blacklist nvidia
blacklist nvidiafb
blacklist radeon
blacklist amdgpu
EOF

# Vincular o device direto ao vfio-pci pelo vendor:device id
lspci -nn -s 01:00.0
# Suponha que retornou [10de:2204] (NVIDIA) e [10de:1aef] (audio HDMI da mesma GPU)
cat > /etc/modprobe.d/vfio.conf <<'EOF'
options vfio-pci ids=10de:2204,10de:1aef disable_vga=1
EOF

update-initramfs -u -k all
reboot

12.5 Adicionar PCI device à VM

Web UI → VM → Hardware → Add → PCI Device:

• Device: escolha o ID (ex: 0000:01:00.0).
• All Functions: marcar (passa .0 e .1 juntos — áudio HDMI da GPU, por ex).
• Primary GPU: marcar somente se for a única GPU da VM e você quer console direto (sem noVNC).
• PCI-Express: marcar para machine q35 (default p/ devices PCIe modernos).
• ROM-Bar: geralmente marcado.

CLI equivalente:

qm set 100 -hostpci0 0000:01:00,pcie=1,x-vga=0,rombar=1

12.6 Caso HBA → TrueNAS

• Crie VM TrueNAS Scale (q35, OVMF, 16+ GB RAM, type host, memory NÃO ballooning).
• Add PCI Device: a controladora HBA (deve estar em IOMMU group isolado).
• Boot do TrueNAS, configure os discos vistos como locais.
• Importante: desligue discard/balloon e fixe RAM mínima = máxima para o ZFS do TrueNAS não brigar.

Não armazene a própria VM do TrueNAS nos discos que ela vai gerenciar via passthrough — coloque-a em local-zfs (rpool), e use os discos passthrough só como pool de dados dela.

13. Cluster (multi-node)

Recomendado se você tem 3+ máquinas. Permite migração ao vivo, HA e ver tudo numa UI só.

13.1 Pré-requisitos

• Mesma versão do PVE em todos os nodes.
• Relógio sincronizado (chrony).
• Resolução DNS recíproca (ou /etc/hosts em cada).
• Latência < 5 ms entre nodes (LAN, idealmente VLAN dedicada para Corosync).
• Portas UDP 5405–5412 (Corosync) + TCP 22 (SSH) liberadas entre eles.
• Sem VMs ainda no node que vai entrar (o join sobrescreve /etc/pve).

13.2 Criar cluster (no node1)

# No pve01
pvecm create labcluster
pvecm status

13.3 Adicionar nodes

# No pve02
pvecm add 192.168.1.11
# (vai pedir a senha root do pve01)

# No pve03
pvecm add 192.168.1.11

Em ~30s os nodes aparecem todos na UI sob Datacenter.

13.4 Rede dedicada para Corosync (recomendado)

Edite /etc/pve/corosync.conf adicionando um segundo ring/link em outra subnet (ex: 10.10.99.x via switch separado). Edite só pelo node1, e bump config_version — o pmxcfs replica para os demais. Erro aqui pode quebrar o cluster.

totem {
    cluster_name: labcluster
    config_version: 5
    interface {
        linknumber: 0
    }
    interface {
        linknumber: 1
    }
    transport: knet
    version: 2
}

nodelist {
    node {
        name: pve01
        nodeid: 1
        quorum_votes: 1
        ring0_addr: 192.168.1.11
        ring1_addr: 10.10.99.11
    }
    node {
        name: pve02
        nodeid: 2
        quorum_votes: 1
        ring0_addr: 192.168.1.12
        ring1_addr: 10.10.99.12
    }
    node {
        name: pve03
        nodeid: 3
        quorum_votes: 1
        ring0_addr: 192.168.1.13
        ring1_addr: 10.10.99.13
    }
}

13.5 QDevice para 2 nodes

Com só 2 nodes, qualquer corte de rede vira split-brain (cada um acha que tem 1 voto). Solução: rodar corosync-qnetd num 3º host externo barato (Raspberry Pi, VM em outro host) e configurar como QDevice:

# No qnetd host (ex: Raspberry Pi com Debian)
apt install -y corosync-qnetd

# Em cada node Proxmox
apt install -y corosync-qdevice

# No node primario
pvecm qdevice setup <IP-do-QDevice-host>
pvecm status

pvecm status deve listar Qdevice como ativo e voto extra.

13.6 HA (High Availability)

Pré-requisitos:

• Cluster com quorum.
• VM em storage compartilhado (Ceph, NFS, iSCSI) — replicação ZFS via pvesr é só semi-HA (RPO ~minutos).

UI: Datacenter → HA → Resources → Add → VM 100, max restart 1, max relocate 3, group default. Se um node morre, o cluster reinicia a VM em outro node em ~2 min (após fencing).

13.7 Migração ao vivo

Com cluster + storage compartilhado (ou replicação):

qm migrate 100 pve02 --online

Para LXC, migração ao vivo só funciona com restart curto (CRIU em LXC é experimental no PVE).

14. Acesso e segurança

14.1 TLS com Let’s Encrypt

Web UI → Datacenter → ACME.

• Accounts → Add: crie conta no Let’s Encrypt (email).
• Challenge Plugin: para ambiente sem porta 80 pública, use DNS Challenge com provider compatível (Cloudflare, etc.). Configure API token.
• Vá em node → Certificates → ACME → Add domain: pve01.lab.example.com, plugin DNS.
• Clique Order Certificates Now.

Depois disso o https://pve01.lab.example.com:8006 mostra cert válido (assumindo seu DNS interno aponta para o host).

14.2 Esconder a UI atrás de VPN

Não exponha 8006 na internet, ponto. Acesso externo: WireGuard ou Tailscale na LAN. Tailscale tem um LXC nice:

pct exec 201 -- bash -c 'curl -fsSL https://tailscale.com/install.sh | sh && tailscale up --advertise-routes=192.168.1.0/24 --advertise-exit-node'

E aprove o subnet route no admin Tailscale. Aí você acessa https://192.168.1.11:8006 de qualquer lugar pela tailnet.

14.3 Firewall do Proxmox

Datacenter → Firewall e Node/VM → Firewall. Modelo:

• Datacenter level: regras globais.
• Node level: regras só para o host.
• VM level: regras só para aquela VM (aplicadas na bridge).

Como cuidado mínimo:

• Aceitar SSH e 8006 só da LAN/VPN.
• Bloquear input do resto.

# Habilitar firewall no datacenter
pvesh set /cluster/firewall/options --enable 1

14.4 fail2ban no host

apt install -y fail2ban
cat > /etc/fail2ban/jail.d/proxmox.conf <<'EOF'
[proxmox]
enabled = true
port = https,http,8006
filter = proxmox
backend = systemd
maxretry = 3
findtime = 2d
bantime = 1h
EOF

cat > /etc/fail2ban/filter.d/proxmox.conf <<'EOF'
[Definition]
failregex = pvedaemon\[.*authentication failure; rhost=<HOST> user=.* msg=.*
ignoreregex =
EOF

systemctl restart fail2ban
fail2ban-client status proxmox

14.5 MFA (TOTP) no admin

UI → topo direito → Permissions → Two Factor → TFA (ou Datacenter → Permissions → Two Factor → Add → TOTP). Use Authy/Aegis/Bitwarden. Imprima/salve recovery keys numa caixa fora do servidor.

Para root@pam, faça a mesma coisa em Datacenter → Permissions → Users → root@pam → TFA.

14.6 Usuário não-root para uso diário

# Criar usuario PAM
useradd -m -s /bin/bash admin
passwd admin
# Adicionar permissoes no Proxmox
pveum useradd admin@pam --comment "Admin"
pveum aclmod / -user admin@pam -role PVEAdmin

Daí você loga com admin@pam na UI e mantém root@pam só para emergências.

15. Monitoramento

15.1 Externo: InfluxDB + Grafana

O Proxmox tem suporte nativo a push de métricas — não precisa exporter.

UI: Datacenter → Metric Server → Add → InfluxDB.

• Server: 192.168.1.30
• Port: 8086
• Organization / Bucket / Token (InfluxDB 2.x) ou DB (1.x)
• Protocolo: http

Stack típica em LXC:

# CT influxdb (200 MB RAM, 10 GB disco)
# CT grafana (200 MB RAM, 2 GB disco)

No Grafana, importe o dashboard oficial Proxmox VE (ID 10048) ou versões mais atualizadas como 15356. Você ganha:

• CPU/RAM/disk por VM e por node.
• IO/network throughput.
• Status do cluster, ZFS pool health.

15.2 Alertas

• SMART: smartd envia email se algum disco degrada (definido em /etc/smartd.conf ou via smartmontools default).
• ZFS: zed (ZFS Event Daemon) — configure /etc/zfs/zed.d/zed.rc com ZED_EMAIL_ADDR.
• vzdump: notificação por job na UI (Notification mode).
• Grafana Alerting: thresholds em CPU/disco/temperatura.

15.3 Logs centralizados (opcional)

Para laboratório, journalctl no host basta. Se quiser centralizar:

• LXC com Loki + Promtail + Grafana.
• Promtail roda em cada node lendo /var/log/syslog e journalctl -o json.

16. Troubleshooting

16.1 VM não dá boot após instalação

Sintoma: “no bootable device” em UEFI. Causas comuns:

• Instalou em BIOS legacy mas a config da VM ficou OVMF (UEFI) (ou vice-versa). Cheque VM → Options → BIOS.
• Sem EFI Disk criado quando usa OVMF. Add em Hardware → Add → EFI Disk.
• Boot order não inclui o disco. Options → Boot Order → habilitar scsi0 (ou onde estiver o disco).
• VM criada com i440fx mas SO espera q35 (Windows 11 etc.). Mudar Machine para q35.

16.2 Passthrough: “Cannot open /dev/vfio/N: No such file or directory”

• IOMMU não habilitado. Verifique dmesg | grep -i iommu.
• Kernel cmdline não foi atualizado (esqueceu update-grub ou proxmox-boot-tool refresh).
• Módulos vfio não carregados — lsmod | grep vfio deve listar 3+ módulos.
• Driver original ainda vinculado (nouveau, nvidia) — blacklist em /etc/modprobe.d/ + update-initramfs -u -k all.

16.3 Passthrough: device some / host trava

• Device no mesmo IOMMU group de algo crítico (NVMe boot, NIC do host). Reordene em outro slot PCIe, ou use ACS override patch (em laboratório, last resort).
• GPU NVIDIA “Code 43”: habilite hidden=1 no flag cpu:

  qm set 100 -cpu host,hidden=1,flags=+pcid

16.4 Corosync split-brain

Sintomas: UI mostra nodes red, pvecm status mostra cluster sem quorum, VMs em HA reiniciando estranhamente.

• Cheque latência: ping -i 0.1 192.168.1.12. Acima de 5 ms é problema.
• Cluster com 2 nodes? Adicione QDevice (seção 13.5).
• Se um node está realmente caído, force quorum no que sobrou (com cuidado):

  pvecm expected 1

• Logs: journalctl -u corosync -u pve-cluster -f.

16.5 ZFS pool DEGRADED

zpool status -v

Se um disco aparece FAULTED ou UNAVAIL:

# Identificar o ruim
zpool status

# Trocar fisicamente o disco, depois substituir no pool
zpool replace rpool /dev/disk/by-id/ata-DEAD-DISK /dev/disk/by-id/ata-NEW-DISK
zpool status   # acompanhar resilver

Para mirror de boot (rpool), depois do replace você precisa reinstalar o bootloader no novo disco:

proxmox-boot-tool format /dev/sdX2
proxmox-boot-tool init /dev/sdX2
proxmox-boot-tool refresh

16.6 Disco do host cheio (/var/lib/vz)

Causa comum: vzdump tmp encheu /var/lib/vz/dump/.

df -h
du -sh /var/lib/vz/* | sort -h

• Mova destino do backup para storage externo (NFS, PBS).
• Configure tmpdir no vzdump apontando para storage maior:

  # /etc/vzdump.conf
  tmpdir: /tank/tmp

16.7 LXC com Docker dentro não inicia containers

• Faltou nesting=1 e/ou keyctl=1. Habilite:

  pct set 200 -features nesting=1,keyctl=1
  pct reboot 200

• Em unprivileged, alguns recursos do Docker (overlay2 sobre certos FSs) não funcionam — use storage driver overlay2 em volume btrfs/ext4, ou parta para privileged se for de confiança.

16.8 Web UI fica em loop de login

• Hora errada: PVE invalida cookie se relógio descalibra. chronyc tracking e timedatectl.
• Browser cache antigo: limpar cookies de pve01:8006.
• Após troca de IP/hostname, regenere certificados:

  pvecm updatecerts --force
  systemctl restart pveproxy

16.9 Perdeu senha root

Boot em modo single-user (rescue) via console, monte rpool/ROOT/pve-1, chroot, passwd root, reboot. Se for ZFS encrypted, precisa da passphrase.

17. Referências

Documentação oficial

• Wiki principal: https://pve.proxmox.com/wiki/Main_Page
• Manual completo (HTML/PDF): https://pve.proxmox.com/pve-docs/
• Admin Guide: https://pve.proxmox.com/pve-docs/pve-admin-guide.html
• Package Repositories: https://pve.proxmox.com/wiki/Package_Repositories
• PCI(e) Passthrough: https://pve.proxmox.com/wiki/PCI(e)_Passthrough
• Cluster Manager: https://pve.proxmox.com/wiki/Cluster_Manager
• Cloud-Init Support: https://pve.proxmox.com/wiki/Cloud-Init_Support
• High Availability: https://pve.proxmox.com/wiki/High_Availability
• Storage: https://pve.proxmox.com/wiki/Storage
• ZFS on Linux: https://pve.proxmox.com/wiki/ZFS_on_Linux
• LXC: https://pve.proxmox.com/wiki/Linux_Container

Comunidade

• Fórum oficial: https://forum.proxmox.com/
• Subreddit: https://www.reddit.com/r/Proxmox/
• Helper-Scripts (community): https://github.com/community-scripts/ProxmoxVE
• tteck legacy scripts: https://tteck.github.io/Proxmox/ (mantenedor original, projeto descontinuado em 2024 — community-scripts é o fork ativo).

Companions

• Proxmox Backup Server: https://pbs.proxmox.com/docs/
• Proxmox Mail Gateway: https://pmg.proxmox.com/docs/
• TrueNAS Scale (para usar com passthrough): https://www.truenas.com/docs/scale/
• Tailscale: https://tailscale.com/kb

Vídeos e tutoriais úteis

• Learn Linux TV — playlist Proxmox: https://www.youtube.com/@LearnLinuxTV
• Jim’s Garage — laboratório Proxmox: https://www.youtube.com/@Jims-Garage
• Christian Lempa — arquitetura de laboratório: https://www.youtube.com/@christianlempa
• Craft Computing (passthrough/GPU): https://www.youtube.com/@CraftComputing

Dashboards Grafana

• Proxmox VE 10048: https://grafana.com/grafana/dashboards/10048
• Proxmox Flux 15356: https://grafana.com/grafana/dashboards/15356

Próximos passos sugeridos:

1. Comprar/montar o host (mini-PC Ryzen com IOMMU decente, 32+ GB RAM ECC se possível, 2x NVMe).
2. Instalar PVE 8.x com ZFS RAID1 no boot, fazer pós-instalação (repos, banner, NTP).
3. Subir uma VM Debian “cobaia” pelo wizard e validar qemu-guest-agent.
4. Criar template cloud-init Debian 13 e provisionar 2-3 clones com IP estático.
5. Subir um LXC Pi-hole/AdGuard, apontar router para ele.
6. Configurar backup automatizado para NAS (NFS) ou PBS em LXC.
7. Quando for fazer TrueNAS com HBA passthrough: testar IOMMU groups antes de comprar a HBA.
8. Habilitar TLS via DNS challenge e MFA no root@pam.
9. Stack Influx+Grafana para visualizar tendências de uso.
10. Se chegar 3 hosts: cluster + replicação ZFS entre nodes.