claude-plugins/infraestrutura/skills/pbs-config/SKILL.md

---
name: pbs-config
description: Configuração Proxmox Backup Server (PBS) - datastore creation, retention policies, sync jobs, remote targets. Use when user mentions "pbs setup", "proxmox backup", "configure pbs", "backup server".
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
---

# PBS Config

Configuração completa de Proxmox Backup Server (PBS) com datastores, políticas de retenção, sync jobs e estratégia de backup 3-2-1.

## Quando Usar

- Configurar PBS após instalação Proxmox
- Criar datastores para backups
- Definir retention policies (7 daily, 4 weekly, 6 monthly)
- Configurar remote sync entre nodes PBS
- Implementar estratégia 3-2-1 backup

## Sintaxe

```bash
/pbs-config <datastore-path> [--retention 7:4:6] [--remote-sync node2] [--dedup on]
```

## Exemplos

```bash
# PBS básico com retention padrão
/pbs-config /mnt/pbs-datastore

# PBS com retention custom e remote sync
/pbs-config /mnt/pbs-datastore --retention 10:5:12 --remote-sync pbs-node2.descomplicar.pt

# PBS sem deduplicação (se storage não suporta)
/pbs-config /mnt/pbs-main --dedup off
```

## Knowledge Sources (Consultar SEMPRE)

### NotebookLM Proxmox Research
```bash
mcp__notebooklm__notebook_query \
  notebook_id:"276ccdde-6b95-42a3-ad96-4e64d64c8d52" \
  query:"proxmox backup server pbs datastore retention deduplication"
```

### Hub Docs
- Hub/05-Projectos/Cluster Descomplicar/Research/Proxmox-VE/Guia-Definitivo-Proxmox-Hetzner.md
- Módulo 3: Storage e Backups (PBS, estratégia 3-2-1, deduplicação)

## Workflow Completo

### Fase 1: PBS Installation (se ainda não instalado)

**1.1 Verificar se PBS já está instalado**
```bash
dpkg -l | grep proxmox-backup-server

# Se não instalado:
apt update
apt install proxmox-backup-server
```

**1.2 Aceder PBS Web UI**
```
https://SERVER_IP:8007

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

**1.3 Configuração Inicial**
- Hostname
- DNS servers
- Time zone (Europe/Lisbon)

### Fase 2: Datastore Creation

**2.1 Preparar Storage**

**Para ZFS (RECOMENDADO):**
```bash
# Já criado em /proxmox-setup:
# zfs create rpool/pbs-datastore

# Verificar
zfs list | grep pbs-datastore

# Optimizar para backup workload
zfs set compression=lz4 rpool/pbs-datastore
zfs set dedup=off rpool/pbs-datastore  # Dedup no PBS, não no ZFS
zfs set recordsize=1M rpool/pbs-datastore  # Large files
```

**Para ext4 (HDD 16TB):**
```bash
# Particionar HDD
parted /dev/sda mklabel gpt
parted /dev/sda mkpart primary ext4 0% 100%

# Formatar
mkfs.ext4 /dev/sda1

# Montar
mkdir -p /mnt/pbs-datastore
echo "/dev/sda1 /mnt/pbs-datastore ext4 defaults 0 2" >> /etc/fstab
mount -a
```

**2.2 Criar Datastore via CLI**
```bash
proxmox-backup-manager datastore create main-store /mnt/pbs-datastore

# Verificar
proxmox-backup-manager datastore list
```

**2.3 Configurar Retention Policy**
```bash
# 7 daily, 4 weekly, 6 monthly (padrão)
proxmox-backup-manager datastore update main-store \
  --keep-daily 7 \
  --keep-weekly 4 \
  --keep-monthly 6 \
  --keep-yearly 3
```

**Explicação Retention:**
- `keep-daily 7`: Mantém 7 backups diários
- `keep-weekly 4`: Mantém 4 backups semanais (1 por semana)
- `keep-monthly 6`: Mantém 6 backups mensais (1 por mês)
- `keep-yearly 3`: Mantém 3 backups anuais

**Gestão automática:** PBS elimina backups antigos baseado nestas regras.

### Fase 3: PBS Users & Permissions

**3.1 Criar User para PVE Backups**
```bash
# User dedicado para Proxmox enviar backups
proxmox-backup-manager user create pve-backup@pbs \
  --email admin@descomplicar.pt

# Password
proxmox-backup-manager user update pve-backup@pbs --password

# Atribuir permissões no datastore
proxmox-backup-manager acl update /datastore/main-store \
  --auth-id pve-backup@pbs \
  --role DatastoreBackup
```

**3.2 Criar API Token (para automação)**
```bash
# Token para scripts/Terraform
proxmox-backup-manager user token create pve-backup@pbs automation-token \
  --output-format json

# Guardar token de forma segura
# Formato: pve-backup@pbs!automation-token=<secret>
```

### Fase 4: Configure PVE to Use PBS

**4.1 Adicionar PBS Storage em Proxmox VE**

Via Web UI (Datacenter → Storage → Add → Proxmox Backup Server):
- ID: `pbs-main`
- Server: `SERVER_IP` (ou hostname se cluster)
- Datastore: `main-store`
- Username: `pve-backup@pbs`
- Password: (password criado)
- Fingerprint: (auto-detect)

Via CLI:
```bash
pvesm add pbs pbs-main \
  --server SERVER_IP \
  --datastore main-store \
  --username pve-backup@pbs \
  --password <password>
```

**4.2 Verificar Conectividade**
```bash
pvesm status | grep pbs-main
```

### Fase 5: Backup Jobs (PVE)

**5.1 Criar Backup Job para VMs Críticas**

Via Web UI (Datacenter → Backup → Add):
- Storage: `pbs-main`
- Schedule: Daily 01:00
- Mode: Snapshot (live backup)
- Compression: zstd
- Notification: email admin@descomplicar.pt

Via CLI:
```bash
# Backup diário de todas VMs às 01:00
vzdump --storage pbs-main --mode snapshot --compress zstd --all 1
```

**5.2 Agendar via cron (alternativa)**
```bash
# /etc/cron.d/pve-backup-critical
0 1 * * * root vzdump --storage pbs-main --vmid 100,101,102 --mode snapshot --compress zstd
```

**5.3 Backup Seletivo**
```bash
# VMs críticas: diário
# VMs secundárias: 3x semana (Seg, Qua, Sex)
0 1 * * 1,3,5 root vzdump --storage pbs-main --vmid 200,201,202 --mode snapshot --compress zstd
```

### Fase 6: Remote Sync (2-Node Cluster)

**Setup para cluster:** PBS em Node B (primary) + PBS em Node A (secondary)

**6.1 Configurar Remote em PBS Secondary (Node A)**

Via Web UI PBS Node A (Configuration → Remote):
- Name: `pbs-node-b`
- Host: `<node-b-ip>` ou `cluster.descomplicar.pt`
- Port: 8007
- Auth ID: `pve-backup@pbs`
- Password: (password)
- Fingerprint: (auto-detect)

**6.2 Criar Sync Job**

Via Web UI PBS Node A (Configuration → Sync Jobs → Add):
- Remote: `pbs-node-b`
- Remote Datastore: `main-store`
- Local Datastore: `secondary-store`
- Schedule: Daily 03:00 (após backups)
- Remove vanished: Yes (sync deletes)

Via CLI em Node A:
```bash
proxmox-backup-manager sync-job create sync-from-node-b \
  --remote pbs-node-b \
  --remote-store main-store \
  --store secondary-store \
  --schedule "0 3 * * *" \
  --remove-vanished true
```

**6.3 Testar Sync Manual**
```bash
proxmox-backup-manager sync-job run sync-from-node-b
```

### Fase 7: Monitoring & Maintenance

**7.1 Verificar Deduplicação**
```bash
# Ver estatísticas datastore
proxmox-backup-manager datastore status main-store

# Ratio deduplicação (típico 1.3-2.5x)
```

**7.2 Garbage Collection**
```bash
# Liberar espaço de backups removidos (retention)
proxmox-backup-manager garbage-collection start main-store

# Agendar GC semanal (Domingo 02:00)
# Via Web UI: Datastore → main-store → Prune & GC
```

**7.3 Verificar Disk Usage**
```bash
df -h /mnt/pbs-datastore

# ZFS
zfs list -o name,used,available,refer rpool/pbs-datastore
```

**7.4 Alertas Email**
```bash
# Configurar notificações
# Via Web UI: Configuration → Notifications
# SMTP server: mail.descomplicar.pt
# Alertas: disk usage >80%, backup failures
```

### Fase 8: Restore Procedures (Testing)

**8.1 Restore VM Teste**

Via Web UI PVE:
- Storage → pbs-main → Backups
- Seleccionar VM backup
- Restore → New VM ID (999)
- Start após restore

**8.2 Restore via CLI**
```bash
# Listar backups disponíveis
pbs-client list --repository pve-backup@pbs@SERVER_IP:main-store

# Restore VM 100
qmrestore pbs-main:backup/vm/100/YYYY-MM-DD... 999
```

**8.3 Validar Restore**
```bash
qm start 999
# Verificar VM boota correctamente
# Teste serviço critical
# Shutdown e remover VM teste
qm stop 999 && qm destroy 999
```

**CRITICAL:** Testar restore ANTES de considerar backup strategy operacional.

## Output Summary

```
✅ PBS configurado: SERVER_IP:8007

💾 Datastore:
   - Name: main-store
   - Path: /mnt/pbs-datastore
   - Size: 16TB (HDD) ou 1TB (NVMe)
   - Deduplication: ON (PBS chunk-based)
   - Compression: LZ4 (ZFS) + zstd (PBS)

📋 Retention Policy:
   - Daily: 7 backups
   - Weekly: 4 backups
   - Monthly: 6 backups
   - Yearly: 3 backups
   - Auto-prune: Yes

🔐 Access:
   - User: pve-backup@pbs
   - Token: automation-token (para CI/CD)
   - Role: DatastoreBackup

⏰ Backup Schedule:
   - Critical VMs (100-102): Diário 01:00
   - Secondary VMs (200-202): Seg/Qua/Sex 01:00
   - GC: Domingo 02:00

🔄 Remote Sync (se cluster):
   - Source: pbs-node-b (Node B)
   - Target: secondary-store (Node A)
   - Schedule: Diário 03:00
   - Remove vanished: Yes

📊 Expected Metrics:
   - Dedup ratio: 1.5-2.5x
   - Compression ratio: 1.3-1.8x
   - Backup speed: 100-300 MB/s (depende network/disk)
   - Restore RTO: 2-4h (para VM 100GB)

✅ Validation Tests:
   ✓ Primeiro backup successful
   ✓ Restore test VM 999
   ✓ Dedup ratio >1.3x
   ✓ Remote sync (se cluster)
   ✓ Email notifications working

📋 Next Steps:
   1. Configurar backup VMs production (/vm-migration)
   2. Criar off-site backup (S3/Wasabi/Hetzner Storage Box)
   3. Documentar restore procedures em PROC-Backup-Restore.md
   4. Testar disaster recovery completo
   5. Monitorizar disk usage PBS (alertar >80%)

⏱️ Setup time: ~30min (vs 1h manual)
```

## Estratégia 3-2-1 Backup

**Implementation para Cluster Descomplicar:**

**3 cópias:**
1. **Original:** VMs em Node A (produção)
2. **Backup primário:** PBS Node B (16TB HDD)
3. **Backup secundário:** PBS Node A remote sync (12TB HDD)

**2 médias diferentes:**
1. NVMe (VMs produção)
2. HDD Enterprise (PBS datastores)

**1 off-site:**
- **Opção A:** Hetzner Storage Box (rsync daily)
- **Opção B:** S3-compatible (Wasabi/Backblaze)
- **Opção C:** PBS em VPS externo

**RPO:** 1h (backups hourly se critical)
**RTO:** 2-4h (restore + validação)

## PBS Advanced Features

### Verification Jobs
```bash
# Verificar integridade backups
proxmox-backup-manager verify-job create verify-main \
  --store main-store \
  --schedule "0 4 * * 0"  # Domingo 04:00
```

### Namespace Organization
```bash
# Organizar backups por tipo
proxmox-backup-manager namespace create main-store/production
proxmox-backup-manager namespace create main-store/testing
proxmox-backup-manager namespace create main-store/archived
```

### Tape Backup (futuro)
- PBS suporta LTO tape
- Para compliance de longo prazo
- Cold storage

## Troubleshooting

### Backup failing: "no space"
```bash
# Verificar disk usage
df -h /mnt/pbs-datastore

# Run GC manual
proxmox-backup-manager garbage-collection start main-store

# Ajustar retention (reduzir keeps)
proxmox-backup-manager datastore update main-store --keep-daily 5
```

### Remote sync not working
```bash
# Verificar conectividade
ping <remote-pbs-ip>

# Testar autenticação
curl -k https://<remote-pbs-ip>:8007/api2/json/access/ticket \
  -d "username=pve-backup@pbs&password=<password>"

# Logs
journalctl -u proxmox-backup -f
```

### Dedup ratio baixo (<1.2x)
```bash
# Verificar se VMs têm dados compressíveis
# VMs com random data (encrypted) não deduplica bem

# Verificar chunk size (padrão 4MB adequado)
proxmox-backup-manager datastore show main-store
```

## References

- **NotebookLM:** 276ccdde-6b95-42a3-ad96-4e64d64c8d52
- **PBS Docs:** https://pbs.proxmox.com/docs/
- **Guia Hub:** Hub/05-Projectos/Cluster Descomplicar/Research/Proxmox-VE/Guia-Definitivo-Proxmox-Hetzner.md (Módulo 3)

---

**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 (#1712)
Tags: pbs, backup, retention, deduplication, sync
Status: Research → Implementation
```

---

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

---

## Quando NÃO Usar

- Para backups ad-hoc manuais (usar vzdump directo)
- Para PBS já configurado (usar troubleshooting guides)
- Para restore procedures (criar skill específica se necessário)