Borgmatic: Copia de Seguridad Cifrada y Automatizada con BorgBackup

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

• Guía de Respaldo con Restic
• Rsync y Rclone para Sincronización de Archivos
• Automatización con Ansible
• Configuración de Nginx