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:

CampoPropósitoValor recomendado
encryption_passphraseProtege la clave del repositorio40+ caracteres aleatorios
compressionAlgoritmo + nivelzstd,3
keep_dailyArchivos diarios retenidos7
keep_weeklyArchivos semanales retenidos4
keep_monthlyArchivos mensuales retenidos6

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ísticaBorgmaticResticDuplicatiKopiaTarsnap
MotorBorgBackupPropioPropioPropioPropio
CifradoAES-256-CTR+HMACAES-256-CTRAES-256AES-256-GCMAES-256-CTR
DeduplicaciónPor trozosDireccionado por contenidoPor bloquesSíSí
ConfiguraciónYAMLFlags CLIGUI/XMLGUI/CLICLI
Hooks DBNativo (PG, MySQL, SQLite)Scripts externosNoNoNo
Solo-anexarSí (servidor SSH)NoNoNoNo
Hooks monitoreoNativo antes/después/errorExternoExternoExternoNo

Errores Comunes y Soluciones

ProblemaSolución
Failed to create/acquire the lockEjecución anterior bloqueada; ejecutar borgmatic borg break-lock /ruta/repo
Repository is not a valid Borg repositoryRuta incorrecta o repo no inicializado; ejecutar borgmatic init
Passphrase provided is incorrectVerificar encryption_passphrase en config coincide con el de inicialización
Connection closed by remote hostClave SSH no en authorized_keys o borg serve no configurado en el remoto
No archives foundPrimer respaldo aún no ejecutado; ejecutar borgmatic create
compact: repository does not support compactionBorg < 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