TL;DR — Resumen Rápido

Borgmatic automatiza copias cifradas y deduplicadas con BorgBackup en Linux. Configura YAML, agenda con systemd timer e implementa estrategia 3-2-1.

Borgmatic convierte la potente pero verbosa CLI de BorgBackup en una configuración YAML declarativa — un solo archivo gestiona respaldos cifrados, deduplicados y comprimidos con políticas de retención, verificaciones de consistencia, hooks de base de datos y notificaciones de monitoreo. Esta guía cubre cada paso desde la instalación hasta una estrategia 3-2-1 lista para producción con volcados de bases de datos e integración de healthchecks.

Requisitos Previos

  • Servidor Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+ o similar)
  • Python 3.8+ (para pip install) o acceso a apt/dnf/pacman
  • Acceso SSH a un destino de respaldo remoto (para respaldos fuera del sitio)
  • Acceso root o sudo
  • Familiaridad básica con YAML y systemd

Fundamentos de BorgBackup

BorgBackup es un programa de respaldo con deduplicación escrito en Python y C. Antes de entender Borgmatic, es esencial comprender qué ofrece Borg:

  • Fragmentación definida por contenido — Borg divide archivos en trozos de tamaño variable basados en hash de contenido, no en bloques fijos. Un archivo grande levemente modificado se deduplica eficientemente porque la mayoría de los trozos son idénticos.
  • Deduplicación — Cada trozo único se almacena exactamente una vez en todos los archivos del repositorio. Un servidor de 100 GB con datos mayormente sin cambios solo requiere megabytes para respaldos posteriores.
  • Cifrado — El modo repokey-blake2 almacena una clave cifrada con AES-256-CTR en el repositorio, protegida por tu frase de contraseña y autenticada con HMAC-SHA256. Un servidor remoto completamente comprometido no expone datos en texto plano.
  • Compresión — lz4 (más rápido, mínimo CPU), zstd (equilibrado, recomendado) o zlib/lzma (máxima relación). zstd,3 es el estándar moderno.
  • Modo solo-anexar — Los repositorios pueden bloquearse para que incluso un cliente comprometido pueda crear nuevos archivos pero no eliminar ni modificar los existentes — el ransomware no puede destruir el historial de respaldos.

Paso 1: Instalar BorgBackup y Borgmatic

Vía pip (recomendado — siempre la última versión):

pip install --upgrade borgmatic

Vía pipx (entorno aislado):

pipx install borgmatic

Vía apt (Ubuntu/Debian):

apt install borgmatic

Vía Docker:

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

Verificar instalación:

borgmatic --version
borg --version

Paso 2: Configurar Borgmatic

Generar una plantilla comentada:

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

Configuración mínima de producción para un servidor web con volcados de base de datos y monitoreo:

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.ejemplo.com:22/~/backups/servidor
    label: remoto-externo

storage:
  encryption_passphrase: "tu-frase-de-contraseña-larga-y-aleatoria"
  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: mi_app_produccion
    username: postgres
    format: custom

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

hooks:
  before_backup:
    - echo "Iniciando respaldo en $(date)"
  after_backup:
    - curl -fsS https://hc-ping.com/tu-uuid > /dev/null
  on_error:
    - echo "Respaldo FALLIDO en $(date)" | mail -s "Error de Respaldo" admin@ejemplo.com

Campos clave de configuración:

Campo Propósito Valor recomendado
encryption_passphrase Protege la clave del repositorio 40+ caracteres aleatorios
compression Algoritmo + nivel zstd,3
keep_daily Archivos diarios retenidos 7
keep_weekly Archivos semanales retenidos 4
keep_monthly Archivos mensuales retenidos 6

Paso 3: Inicializar el Repositorio

Inicializar cada repositorio antes del primer respaldo:

borgmatic init --encryption repokey-blake2

Para un repositorio remoto en modo solo-anexar (muy recomendado para seguridad fuera del sitio):

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

# Luego inicializar normalmente desde el cliente
borgmatic init --encryption repokey-blake2

Exportar y almacenar la clave del repositorio fuera de línea — esto es crítico:

borg key export /var/backup/local-borg /root/clave-borg-respaldo.txt
# Guardar en un gestor de contraseñas Y en una USB fuera del sitio

Paso 4: Ejecutar y Programar Respaldos

Primer respaldo (verboso para verificar que todo funciona):

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

Operaciones regulares:

borgmatic          # crear + podar + compactar + verificar (ejecución completa)
borgmatic create   # solo respaldo
borgmatic prune    # aplicar política de retención, eliminar archivos antiguos
borgmatic compact  # recuperar espacio liberado (requiere Borg 1.2+)
borgmatic check    # verificar integridad del repositorio y archivos

Ver archivos disponibles:

borgmatic list
borgmatic info --archive latest

Paso 5: Programar con Timer de systemd

Borgmatic incluye una unidad de servicio y timer de systemd. Habilitarlos:

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

El timer predeterminado se ejecuta diariamente a una hora aleatoria dentro de la ventana de mantenimiento. Para personalizar el horario, crear un archivo de anulación:

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

Paso 6: Procedimientos de Restauración

Listar archivos disponibles:

borgmatic list

Restaurar archivos o directorios específicos:

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

Restaurar una base de datos PostgreSQL:

borgmatic restore --archive latest --database mi_app_produccion

Montar un archivo con FUSE para exploración:

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

Comparación: Borgmatic vs Alternativas

Característica Borgmatic Restic Duplicati Kopia Tarsnap
Motor BorgBackup Propio Propio Propio Propio
Cifrado AES-256-CTR+HMAC AES-256-CTR AES-256 AES-256-GCM AES-256-CTR
Deduplicación Por trozos Direccionado por contenido Por bloques Sí Sí
Configuración YAML Flags CLI GUI/XML GUI/CLI CLI
Hooks DB Nativo (PG, MySQL, SQLite) Scripts externos No No No
Solo-anexar Sí (servidor SSH) No No No No
Hooks monitoreo Nativo antes/después/error Externo Externo Externo No

Errores Comunes y Soluciones

Problema Solución
Failed to create/acquire the lock Ejecución anterior bloqueada; ejecutar borgmatic borg break-lock /ruta/repo
Repository is not a valid Borg repository Ruta incorrecta o repo no inicializado; ejecutar borgmatic init
Passphrase provided is incorrect Verificar encryption_passphrase en config coincide con el de inicialización
Connection closed by remote host Clave SSH no en authorized_keys o borg serve no configurado en el remoto
No archives found Primer respaldo aún no ejecutado; ejecutar borgmatic create
compact: repository does not support compaction Borg < 1.2 en el servidor; actualizar BorgBackup

Resumen

  • BorgBackup proporciona fragmentación definida por contenido, deduplicación, cifrado AES-256-CTR, compresión lz4/zstd/zlib y modo solo-anexar.
  • Borgmatic envuelve Borg en un único config YAML cubriendo create, prune, compact, check, hooks de base de datos y notificaciones de monitoreo.
  • Timer de systemd gestiona la programación con RandomizedDelaySec para evitar picos de carga.
  • Hooks de base de datos (PostgreSQL pg_dump, MySQL mysqldump, SQLite) aseguran instantáneas consistentes sin detener los servicios.
  • Estrategia 3-2-1 — tres copias, dos tipos de medios, una fuera del sitio — implementada listando múltiples repositorios en un config.
  • Siempre prueba las restauraciones antes de necesitarlas; borgmatic check verifica integridad pero solo un extract exitoso confirma que se puede restaurar.

Artículos Relacionados