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:

CampoPropósitoValor recomendado
encryption_passphraseProtege a chave do repositório40+ caracteres aleatórios
compressionAlgoritmo + nívelzstd,3
keep_dailyArquivos diários retidos7
keep_weeklyArquivos semanais retidos4
keep_monthlyArquivos mensais retidos6

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

RecursoBorgmaticResticDuplicatiKopiaTarsnap
MotorBorgBackupPróprioPróprioPróprioPróprio
CriptografiaAES-256-CTR+HMACAES-256-CTRAES-256AES-256-GCMAES-256-CTR
DeduplicaçãoPor blocosEndereçado por conteúdoPor blocosSimSim
ConfiguraçãoYAMLFlags CLIGUI/XMLGUI/CLICLI
Hooks BDNativo (PG, MySQL, SQLite)Scripts externosNãoNãoNão
Somente-anexarSim (servidor SSH)NãoNãoNãoNão
Hooks monitoramentoNativo antes/depois/erroExternoExternoExternoNão

Problemas Comuns

ProblemaSolução
Failed to create/acquire the lockExecução anterior travada; executar borgmatic borg break-lock /caminho/repo
Repository is not a valid Borg repositoryCaminho incorreto ou repo não inicializado; executar borgmatic init
Passphrase provided is incorrectVerificar encryption_passphrase na config coincide com a usada na inicialização
Connection closed by remote hostChave SSH não em authorized_keys ou borg serve não configurado no remoto
No archives foundPrimeiro backup ainda não executado; executar borgmatic create
compact: repository does not support compactionBorg < 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