Sistema de backup pull para Proxmox VE

Paso 4: Crear la configuracion principal

cd ~/utilidades/proxmox-backup/pull
cp /root/backups/pull/config/pull-backup.cfg.example \
   /root/backups/pull/config/pull-backup.cfg
cp config/proxmox_hosts.cfg.example hosts/proxmox_hosts.cfg

Editar los valores segun el entorno:config/pull-backup.cfg:

# Directorios
incoming_dir="/srv/storage/backups_kvm/incoming"
final_dir="/srv/storage/backups_kvm/snapshots"

# Retencion
numcopias=3

# Snapshots
(v2.0.0)
snapshot_pct=15          # Porcentaje del LV para snapshot
(default 15)
default_vm_scope="all"   # "all" = descubre y respalda todas las VMs; "none" = requiere filtro explicito

# Rendimiento
min_speed_mbs=150    # MB/s minimos esperados (para timeout dinamico)
min_free_gb=1024500      # GB libres requeridos (ademas del tamano estimado)
ssh_timeout=30       # Timeout SSH en segundos

# Lock distribuido (v2.1.0+, obligatorio si hay multiples storages)
caller_id="mystor01"    # Identificador unico de este storage
lock_ttl=7200            # TTL del lock en segundos (2h)

# Permisos de ficheros
file_owner="backupuser:backupuser"   # chown tras escribir

# Notificaciones (solo en errores)
correo="admin@example.com"

Paso

Editar 5: Revisar el inventario de hosts

cat /root/backups/pull/hosts/proxmox_hosts.cfg

Formato CSV::

# name,host,port,key_file,disks_file
avanza01,ns3248916.ip-91-134-71.eu,myprox01,10.0.0.1,22,/root/backups/pull/keys/id_pull_backup,

El campo disks_file es opcional desde v2.0.0. Si se deja vacio yCon default_vm_scope="all", el orquestador descubre automaticamente todas las VMs activas via el comando list.activas.

Paso 5: Crear directorios de datos

mkdir -p /srv/storage/backups_kvm/incoming
mkdir -p /srv/storage/backups_kvm/snapshots
mkdir -p ~/utilidades/proxmox-backup/pull/logs

Paso 6: Verificar conectividad

cd ~/utilidades/proxmox-backup/pull
./proxmox-pull-backup.sh --host myprox01 --verbose --dry-run

Paso 7: Configurar cron

# Backup diario a las 10:02:00 UTC
echocrontab "-e
0 102 * * * ~/root/backups/utilidades/proxmox-backup/pull/proxmox-pull-backup.sh >> ~/root/backups/utilidades/proxmox-backup/pull/logs/cron.log 2>&1" | crontab -1

IMPORTANTE con multiples storages: escalonar los crons con al menos 15 minutos de diferencia. Aunque el lock distribuido previene colisiones, la separacion temporal reduce contention.

Actualizacion

cd ~/utilidades
git pull

No requiere reinicio. Los scripts se invocan frescos en cada ejecucion.

Uso diario

Ejecutar backup manual

cd ~/utilidades/proxmox-backup/pull

# Dry-run (no ejecuta nada, muestra lo que haria)
./proxmox-pull-backup.sh --host prox06myprox01 --verbose --dry-run

# Backup real de todas las VMs de un host
./proxmox-pull-backup.sh --host prox06myprox01 --verbose

# Backup de una VM especifica
./proxmox-pull-backup.sh --host prox06myprox01 --vm 104 --verbose

# Backup de varias VMs (separadas por coma o repetido)
./proxmox-pull-backup.sh --host prox06myprox01 --vm 104,203 --verbose

# Backup de todos los hosts configurados
./proxmox-pull-backup.sh --verbose

Listar backups disponibles

python3 proxmox-pull-restore.py --config config/pull-backup.cfg list

# Filtrar por host
python3 proxmox-pull-restore.py --config config/pull-backup.cfg list --host prox06myprox01

# Filtrar por VM
python3 proxmox-pull-restore.py --config config/pull-backup.cfg list --vm 316

Restaurar una VM

Escenario A: la VM existe y esta parada (sobreescribe los discos):

python3 proxmox-pull-restore.py --config config/pull-backup.cfg \
  restore --host prox06myprox01 --vm 316 --data-only

Escenario B: la VM no existe (crea LV, config y restaura datos):

python3 proxmox-pull-restore.py --config config/pull-backup.cfg \
  restore --host prox06myprox01 --vm 316 --from-scratch

Restaurar desde una fecha concreta:

python3 proxmox-pull-restore.py --config config/pull-backup.cfg \
  restore --host prox06myprox01 --vm 316 --date 2026-02-08

Restaurar varias VMs en paralelo:

python3 proxmox-pull-restore.py --config config/pull-backup.cfg \
  restore --host prox06myprox01 --vm 316 900 --workers 2

IMPORTANTE: el argumento --config va ANTES del subcomando (list, restore).

Modelo de seguridad

Lado Proxmox

El helper (proxmox-backup-helper.sh) se ejecuta exclusivamente via la restriccion command= en authorized_keys. Esto significa que cualquier conexion SSH con esa clave ejecuta el helper, ignorando el comando solicitado por el cliente.

El helper valida cada argumento con expresiones regulares estrictas:

• Volume groups: solo alfanumericos, guiones y guiones bajos
• Logical volumes: solo patron vm-\d+-disk-\d+
• Snapshot names: solo patron snap-\d+-disk\d+
• VMIDs: solo numeros entre 100 y 999999
• Snapshot porcentaje: solo numeros entre 1 y 100
• caller_id: solo alfanumericos, guiones y guiones bajos (v2.1.0)

Comandos no reconocidos se rechazan con error. Todas las operaciones se registran en syslog.

Lado Storage

El storage inicia todas las conexiones. Proxmox nunca se conecta al storage para los backups. El unico acceso inverso (Proxmox hacia storage) es para restore, y se canaliza a traves de backup-access-shell.sh que solo permite operaciones de lectura (pigz -dc, ls, test, cat, du) y valida rutas con readlink -f contra symlinks maliciosos.

Estructura de ficheros

En el servidor de storage

~/root/backups/utilidades/proxmox-backup/pull/
  proxmox-pull-backup.sh        # Orquestador v2.0.01.2
  proxmox-pull-restore.py       # Herramienta de restore
  backup-access-shell.sh        # Shell read-only
  install-pull-backup.sh        # Instalador
  config/
    pull-backup.cfg              # Configuracion principal (gitignored)
    pull-backup.cfg.example      # Template (versionado)
  hosts/
    proxmox_hosts.cfg            # Inventario de hosts disks_prox06.(gitignored)
    disks_myprox01.txt           # (Opcional) filtro de discos (gitignored)
  keys/
    id_pull_backup               # Clave privada SSH (gitignored)
    id_pull_backup.pub           # Clave publica SSH (gitignored)
  logs/
    pull-backup-YYYY-MM-DD.log   # Log diario (gitignored)
    cron.log                     # Log de cron (gitignored)

En el servidor Proxmox

~/usr/local/bin/utilidades/proxmox-backup/pull/
  proxmox-backup-helper.sh      # Helper restringido v2.0.01.1

/root/.ssh/authorized_keys      # Clave con command=
/run/pull-backup/               # Lock files distribuidos (runtime)

Directorio de backups

/srv/storage/backups_kvm/
  incoming/                                # Transferencias en curso
  snapshots/
    kvm-104-disk0.2026-02-26-10-00-12.gz   # Disco 0 comprimido
    kvm-104-disk1.2026-02-26-10-00-12.gz   # Disco 1 (mismo timestamp)
    kvm-104.conf.2026-02-26-10-00-12       # Config de la VM

Nomenclatura de ficheros

kvm-{vmid}-disk{N}.{YYYY-MM-DD-HH-MM-SS}.gz    # Discos
kvm-{vmid}.conf.{YYYY-MM-DD-HH-MM-SS}           # Configuraciones

Comandos del helper

El helper v2.0.01.1 acepta 1213 comandos, todos validados con regex:

Formato del manifest (snapshot-vm)

# snap_name,vg,lv,size_gb
snap-104-disk0,pve,vm-104-disk-0,150
snap-104-disk1,pve,vm-104-disk-1,125

Opciones del orquestador

proxmox-pull-backup.sh [--config <path>] [--host <name>] [--vm <vmid>[,<vmid>...]] [--dry-run] [--force] [--verbose]

  --config <path>            Fichero de configuracion (default: ./config/pull-backup.cfg)
  --host <name>              Backup solo este host (default: todos los hosts)
  --vm <vmid>[,<vmid>...]    Backup solo estas VMs (separadas por coma, repetible)
  --dry-run                  Muestra lo que haria sin ejecutar
  --force                    Auto-limpieza de snapshots huerfanos en Proxmox
  --verbose                  Salida detallada

Parametros de configuracion

Funcionalidades avanzadas

Descubrimiento dinamico (v2.0.0)

Con default_vm_scope="all" en la config, el orquestador descubre automaticamente todas las VMs activas usando el comando list del helper. Los ficheros disks_*.txt pasan a ser opcionales (filtro de exclusion, no inventario obligatorio).

Timeout dinamico

El timeout de cada transferencia se calcula automaticamente segun el tamano del disco:

timeout = (tamano_disco_gb * 1024) / min_speed_mbs

Con un minimo de 300 segundos. Para un disco de 150GB a 150 MB/s el timeout es ~17 minutos.

Deteccion de snapshots huerfanos

Antes de procesar cada host, el orquestador ejecuta list-snapshots y compara con los snapshots esperados. Los huerfanos (de ejecuciones previas fallidas) se limpian automaticamente si force_orphan_cleanup=1.

Estimacion de tamano

Si existe un backup previo del mismo disco, se usa su tamano como estimacion. Si no, se estima el 50% del tamano raw del disco. Esto se usa para la verificacion de espacio libre.

Verificacion de integridad

Tras cada transferencia, se ejecuta pigz -t sobre el fichero comprimido para verificar integridad. Si falla, se descarta el fichero y se reintenta.

Reintentos

Si un backup falla, se reintenta una vez tras 10 minutos de espera. Solo se reporta error si el segundo intento tambien falla. Si falla el reintento, la VM completa se marca como fallida (all-or-nothing).

Pruning automatico

Tras completar los backups, se mantienen solo las ultimas numcopias copias de cada disco. Las configs asociadas a backups eliminados tambien se limpian.

Rendimiento validado

Produccion (avanza01marzo + stor01avanzait, febrero 2026)

KVM 104 — 2 discos, snapshots atomicos2026, v2.0.0:

TotalMejora v2.1.2: 171La GBeliminacion comprimidos,de 3657sla (verificacion pigz -t post-transferencia redujo el tiempo total de KVM 104 de ~61 min)min incluyendo(v2.0.0) snapshots,a transfers,~14.5 verificacionmin y— cleanup.aceleracion de 4x. La integridad de la compresion se valida on-the-fly via PIPESTATUS del pipeline dd | pigz.

Staging (avanza02 + stor01avanzait, febrero 2026)

Despliegues actuales

Troubleshooting

El backup genera un fichero .gz invalido

Causa: Los comandos lvcreate/lvremove escriben mensajes a stdout que contaminan el stream gzip.

Solucion: Verificar que el helper redirige stdout de lvm a stderr (>&2). Actualizar el helper a v2.0.0.1.1+.

ErrorVM "integerbloqueada expressionpor expected"otro enstorage el(exit installer80)

Causa: grepOtro -cstorage viaesta SSHrespaldando devuelveesa multiplesVM. lineasEl lock distribuido (0\n0),v2.1.0) bashpreviene nola puede comparar.colision.

Solucion: BugEs menorun conocido,comportamiento nocorrecto. afectaLa VM se salta limpiamente y se respalda en la siguiente ejecucion. Si el lock es huerfano (proceso anterior murio), esperar a laque instalacion. El paso 3 completa correctamente.

El installer falla enexpire el testTTL de(default restriccion

Causa:o setlimpiar -euo pipefail captura el exit code 1 del helper cuando rechaza un comando no autorizado.

Solucion: Bug menor conocido. La restriccion funciona correctamente. Verificar manualmente con:manualmente:

ssh -i keys/id_pull_backup proxmox "lscleanup-vm /<vmid> <caller_id>"
# Debe devolver: ERROR: Unknown command: ls

ElSnapshot/lock restorehuerfano dicetras "pigz:matar unrecognizedun format"proceso

Causa: ElSi ficherose .gzmata estael corruptoproceso del orquestador (verkill primer-9), problema).pueden quedar snapshots y locks huerfanos en Proxmox.

Solucion: RehacerLimpiar elmanualmente:

ssh con-i elkeys/id_pull_backup helperproxmox v2.0.0.
"cleanup-vm <vmid> <caller_id>"

Timeout en backups de discos grandes

Causa: El timeout dinamico depende de min_speed_mbs en la config.

Solucion: Reducir min_speed_mbs si la red es lenta. Por ejemplo, para 50 MB/s reales:

min_speed_mbs=40   # Dejar margen del 20%

Snapshot overflow (snap_percent=100)

Causa: El disco recibe mas escrituras de las esperadas durante la transferencia, llenando el snapshot COW.

Solucion: Aumentar snapshot_pct en la config (default: 15). Para VMs con alta actividad de I/O, usar 20-25.

El restore dice "pigz: unrecognized format"

Causa: El fichero .gz esta corrupto.

Solucion: Rehacer el backup con el helper v2.1.1+.

Repositorio

El codigo fuente esta en el repositorio utilidades bajo proxmox-backup/pull/.

Documentacion completa: proxmox-backup/README.md y proxmox-backup/docs/SPEC-pull-backup-architecture.md.

Historial de versiones

Ultima actualizacion

• Fecha: 2026-02-2603-02
• Version: 2.0.01.2
• Autor: Abkrim