Borgmatic: Backup Criptografado e Automatizado com BorgBackup

TL;DR — Resumo Rápido

Borgmatic automatiza backups cifrados e deduplicados com BorgBackup no Linux. Configure YAML, agende com systemd timers e implemente estratégia 3-2-1 de backup.

Borgmatic converte a poderosa mas verbosa CLI do BorgBackup em uma configuração YAML declarativa — um único arquivo gerencia backups criptografados, deduplicados e comprimidos com políticas de retenção, verificações de consistência, hooks de banco de dados e notificações de monitoramento. Este guia cobre cada passo desde a instalação até uma estratégia 3-2-1 pronta para produção com dumps de banco de dados e integração de healthchecks.

Pré-requisitos

• Servidor Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+ ou similar)
• Python 3.8+ (para pip install) ou acesso ao apt/dnf/pacman
• Acesso SSH a um destino de backup remoto (para backups externos)
• Acesso root ou sudo
• Familiaridade básica com YAML e systemd

---

Fundamentos do BorgBackup

BorgBackup é um programa de backup com deduplicação escrito em Python e C. Antes de entender o Borgmatic, é essencial compreender o que o Borg oferece:

• Fragmentação definida por conteúdo — O Borg divide arquivos em blocos de tamanho variável baseados em hash de conteúdo, não em blocos fixos. Um arquivo grande levemente modificado se deduplica eficientemente porque a maioria dos blocos é idêntica.
• Deduplicação — Cada bloco único é armazenado exatamente uma vez em todos os arquivos do repositório. Um servidor de 100 GB com dados majoritariamente inalterados requer apenas megabytes para backups posteriores.
• Criptografia — O modo repokey-blake2 armazena uma chave criptografada com AES-256-CTR no repositório, protegida pela frase-senha e autenticada com HMAC-SHA256. Um servidor remoto totalmente comprometido não expõe dados em texto claro.
• Compressão — lz4 (mais rápido, mínimo de CPU), zstd (equilibrado, recomendado) ou zlib/lzma (máxima taxa). zstd,3 é o padrão moderno.
• Modo somente-anexar — Repositórios podem ser bloqueados para que mesmo um cliente comprometido possa criar novos arquivos mas não possa excluir ou modificar os existentes.

---

Passo 1: Instalar BorgBackup e Borgmatic

Via pip (recomendado — sempre a versão mais recente):

pip install --upgrade borgmatic

Via pipx (ambiente isolado):

pipx install borgmatic

Via apt (Ubuntu/Debian):

apt install borgmatic

Via Docker:

docker run --rm \
  -v /etc/borgmatic:/etc/borgmatic \
  -v /var/backup:/backup \
  ghcr.io/borgmatic-collective/borgmatic

Verificar instalação:

borgmatic --version
borg --version

---

Passo 2: Configurar o Borgmatic

Gerar um template comentado:

mkdir -p /etc/borgmatic
borgmatic config generate --destination /etc/borgmatic/config.yaml

Configuração mínima de produção para um servidor web com dumps de banco de dados e monitoramento:

source_directories:
  - /etc
  - /var/www
  - /home

repositories:
  - path: /var/backup/local-borg
    label: local
  - path: ssh://backup@192.168.1.100/~/backups/servidor
    label: remoto-lan
  - path: ssh://backup@externo.exemplo.com:22/~/backups/servidor
    label: remoto-externo

storage:
  encryption_passphrase: "sua-frase-senha-longa-e-aleatoria-aqui"
  compression: "zstd,3"
  archive_name_format: "{hostname}-{now:%Y-%m-%dT%H:%M:%S}"
  checkpoint_interval: 1800

retention:
  keep_daily: 7
  keep_weekly: 4
  keep_monthly: 6
  keep_yearly: 1

postgresql_databases:
  - name: minha_app_producao
    username: postgres
    format: custom

mysql_databases:
  - name: wordpress
    username: root
    options: "--single-transaction"

hooks:
  before_backup:
    - echo "Iniciando backup em $(date)"
  after_backup:
    - curl -fsS https://hc-ping.com/seu-uuid > /dev/null
  on_error:
    - echo "Backup FALHOU em $(date)" | mail -s "Erro de Backup" admin@exemplo.com

Campos chave de configuração:

Campo	Propósito	Valor recomendado
encryption_passphrase	Protege a chave do repositório	40+ caracteres aleatórios
compression	Algoritmo + nível	zstd,3
keep_daily	Arquivos diários retidos	7
keep_weekly	Arquivos semanais retidos	4
keep_monthly	Arquivos mensais retidos	6

---

Passo 3: Inicializar o Repositório

Inicializar cada repositório antes do primeiro backup:

borgmatic init --encryption repokey-blake2

Para um repositório remoto em modo somente-anexar (altamente recomendado para segurança externa):

# No servidor de backup, editar ~/.ssh/authorized_keys:
command="borg serve --restrict-to-path /home/backup/backups --append-only",restrict ssh-rsa AAAA... cliente@servidor

# Depois inicializar normalmente a partir do cliente
borgmatic init --encryption repokey-blake2

Exportar e armazenar a chave do repositório offline — isso é crítico:

borg key export /var/backup/local-borg /root/chave-borg-backup.txt
# Guardar em gerenciador de senhas E em pendrive mantido fora do local

---

Passo 4: Executar e Agendar Backups

Primeiro backup (verboso para verificar que tudo funciona):

borgmatic create --verbosity 1 --list --stats

Operações regulares:

borgmatic          # criar + podar + compactar + verificar (execução completa)
borgmatic create   # apenas backup
borgmatic prune    # aplicar política de retenção, remover arquivos antigos
borgmatic compact  # recuperar espaço liberado (requer Borg 1.2+)
borgmatic check    # verificar integridade do repositório e arquivos

Ver arquivos disponíveis:

borgmatic list
borgmatic info --archive latest

---

Passo 5: Agendar com Timer do systemd

O Borgmatic inclui uma unidade de serviço e timer do systemd. Ativá-los:

systemctl enable --now borgmatic.timer
systemctl status borgmatic.timer

O timer padrão executa diariamente em um horário aleatório dentro da janela de manutenção. Para personalizar o horário, criar um arquivo de substituição:

# /etc/systemd/system/borgmatic.timer.d/override.conf
[Timer]
OnCalendar=
OnCalendar=*-*-* 02:30:00
RandomizedDelaySec=30min

systemctl daemon-reload
systemctl restart borgmatic.timer

---

Passo 6: Procedimentos de Restauração

Listar arquivos disponíveis:

borgmatic list

Restaurar arquivos ou diretórios específicos:

borgmatic extract \
  --archive servidor-2026-03-23T02:30:00 \
  --path /var/www/minhaapp \
  --destination /tmp/restaurar

Restaurar um banco de dados PostgreSQL:

borgmatic restore --archive latest --database minha_app_producao

Montar um arquivo com FUSE para navegação:

borgmatic mount --archive latest --mount-point /mnt/borg
ls /mnt/borg
borgmatic umount --mount-point /mnt/borg

---

Comparação: Borgmatic vs Alternativas

Recurso	Borgmatic	Restic	Duplicati	Kopia	Tarsnap
Motor	BorgBackup	Próprio	Próprio	Próprio	Próprio
Criptografia	AES-256-CTR+HMAC	AES-256-CTR	AES-256	AES-256-GCM	AES-256-CTR
Deduplicação	Por blocos	Endereçado por conteúdo	Por blocos	Sim	Sim
Configuração	YAML	Flags CLI	GUI/XML	GUI/CLI	CLI
Hooks BD	Nativo (PG, MySQL, SQLite)	Scripts externos	Não	Não	Não
Somente-anexar	Sim (servidor SSH)	Não	Não	Não	Não
Hooks monitoramento	Nativo antes/depois/erro	Externo	Externo	Externo	Não

---

Problemas Comuns

Problema	Solução
Failed to create/acquire the lock	Execução anterior travada; executar borgmatic borg break-lock /caminho/repo
Repository is not a valid Borg repository	Caminho incorreto ou repo não inicializado; executar borgmatic init
Passphrase provided is incorrect	Verificar encryption_passphrase na config coincide com a usada na inicialização
Connection closed by remote host	Chave SSH não em authorized_keys ou borg serve não configurado no remoto
No archives found	Primeiro backup ainda não executado; executar borgmatic create
compact: repository does not support compaction	Borg < 1.2 no servidor; atualizar BorgBackup

Resumo

• BorgBackup fornece fragmentação definida por conteúdo, deduplicação, criptografia AES-256-CTR, compressão lz4/zstd/zlib e modo somente-anexar.
• Borgmatic envolve o Borg em um único config YAML cobrindo create, prune, compact, check, hooks de banco de dados e notificações de monitoramento.
• Timer do systemd gerencia o agendamento com RandomizedDelaySec para evitar picos de carga.
• Hooks de banco de dados (PostgreSQL pg_dump, MySQL mysqldump, SQLite) garantem snapshots consistentes sem parar os serviços.
• Estratégia 3-2-1 — três cópias, dois tipos de mídia, uma externa — implementada listando múltiplos repositórios em um config.
• Sempre teste as restaurações antes de precisar delas; borgmatic check verifica integridade mas apenas um extract bem-sucedido confirma a restaurabilidade.

Artigos Relacionados

• Guia de Backup com Restic
• Rsync e Rclone para Sincronização de Arquivos
• Automação com Ansible
• Configuração do Nginx