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

name, description, author, version, quality_score, user_invocable, desk_task, allowed-tools, dependencies

name	description	author	version	quality_score	user_invocable	desk_task	allowed-tools	dependencies
pbs-config	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".	Descomplicar® Crescimento Digital	1.0.0	75	true	1712	Task, Read, Bash	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

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

Exemplos

# 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

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

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):

# 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):

# 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

proxmox-backup-manager datastore create main-store /mnt/pbs-datastore

# Verificar
proxmox-backup-manager datastore list

2.3 Configurar Retention Policy

# 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

# 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)

# 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:

pvesm add pbs pbs-main \
  --server SERVER_IP \
  --datastore main-store \
  --username pve-backup@pbs \
  --password <password>

4.2 Verificar Conectividade

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:

# 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)

# /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

# 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:

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

proxmox-backup-manager sync-job run sync-from-node-b

Fase 7: Monitoring & Maintenance

7.1 Verificar Deduplicação

# Ver estatísticas datastore
proxmox-backup-manager datastore status main-store

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

7.2 Garbage Collection

# 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

df -h /mnt/pbs-datastore

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

7.4 Alertas Email

# 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

# 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

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

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

Namespace Organization

# 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"

# 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

# 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)

# 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)