1. Introducción
Proxmox Backup Server (PBS) es la solución de copias de seguridad de Proxmox: almacena, deduplica y verifica los backups de máquinas virtuales (KVM) y contenedores (LXC) que generan los hosts Proxmox VE (PVE).
Core-Admin incluye la herramienta de línea de comandos crad-pbs-mgr.pyc para inventariar, diagnosticar, auditar, restaurar y mantener un PBS (y, en parte, los hosts PVE que le envían los backups). Está pensada para responder con un solo comando a preguntas habituales del día a día:
- ¿Qué datastores y backups hay y cuánto ocupan?
- ¿Cuándo fue la última copia de una VM/CT y por qué lleva días sin respaldarse?
- ¿Qué máquinas se están quedando sin backups recientes (auditoría de cobertura)?
- ¿Cómo restauro un snapshot concreto?
- El disco
/del PBS se está llenando de logs de tareas, ¿cómo lo limpio de forma segura?
La herramienta es de solo lectura salvo en tres operaciones que modifican el sistema y están claramente marcadas: la restauración (--restore), la purga de logs de tareas (--purge-task-logs) y la gestión de la lista de exclusiones de la auditoría (--ignore-vmid / --unignore-vmid). Todas las operaciones destructivas piden confirmación (salvo que se pase -y).
Este artículo describe todas las opciones y capacidades de la herramienta, agrupadas por bloques funcionales, e incluye una tabla resumen y ejemplos prácticos.
2. Requisitos previos
- Debe ejecutarse como
root(los directorios de los datastores y los logs de tareas requieren privilegios de root para leerse). Si no se ejecuta como root, la herramienta aborta con un error. - Debe ejecutarse sobre un host Proxmox Backup Server o Proxmox VE. Si no detecta ninguno de los dos, aborta.
- No requiere argumentos de conexión: la herramienta trabaja directamente contra el sistema local (ficheros de configuración,
proxmox-backup-manager, layout de los datastores en disco, etc.).
Sin argumentos, la herramienta muestra la ayuda completa con todas las opciones:
crad-pbs-mgr.pyc
3. Detección automática de entorno (PBS / PVE / ambos)
Al arrancar, la herramienta detecta el rol del host y habilita o restringe las operaciones en función de él:
| Rol detectado | Cómo se detecta | Operaciones disponibles |
|---|---|---|
| PBS | Existe proxmox-backup-manager o /etc/proxmox-backup/datastore.cfg
|
Inventario, diagnóstico, auditoría, jobs PBS, purga de logs |
| PVE | Existe pvesm o /etc/pve/storage.cfg
|
Restauración, jobs de backup (vzdump), diagnóstico |
| both | Se cumplen ambas condiciones | Todas |
| unknown | Ninguna de las anteriores | Ninguna (aborta) |
Esto es importante porque la información de PBS y la de PVE está repartida: los snapshots y las tareas viven en el PBS, pero la programación de los backups (cuándo y a quién se respalda) vive en el host PVE, en /etc/pve/jobs.cfg. Algunas opciones (como la auditoría de cobertura o el diagnóstico) son más completas si se ejecutan en un host que sea a la vez PBS y PVE, o cruzando la información de ambos.
4. Filtros comunes
La mayoría de listados y operaciones aceptan estos filtros, que pueden combinarse:
| Opción | Significado |
|---|---|
--vmid VMID |
Filtra por identificador de invitado (VMID de la VM/CT). |
--type TYPE |
Filtra por tipo de invitado: ct (LXC) o vm (KVM). Se aceptan alias: lxc/container → ct, kvm/qemu → vm. |
--datastore NAME |
Filtra por nombre de datastore. |
--limit N |
Número máximo de tareas a listar (por defecto 100). |
--task-type TYPE |
Filtra --list-tasks por tipo de worker: backup, verify, sync, gc, prune. |
5. Inventario: datastores, backups y snapshots
5.1. --list-datastores
Lista los datastores configurados en el PBS (nombre, ruta en disco y comentario). Intenta usar proxmox-backup-manager datastore list y, si no, cae a leer /etc/proxmox-backup/datastore.cfg.
crad-pbs-mgr.pyc --list-datastores
5.2. --list-backups
Lista los grupos de backup, es decir, una fila por VMID, resumiendo todos sus snapshots. Para cada grupo muestra: datastore, tipo (ct/vm/host), VMID, número de snapshots, fecha del primer y del último backup y tamaño total ocupado.
crad-pbs-mgr.pyc --list-backups
crad-pbs-mgr.pyc --list-backups --datastore backup --type ct
Es la vista ideal para una foto rápida de “qué máquinas tengo respaldadas y cuándo fue la última copia”.
5.3. --list-snapshots
Lista los snapshots individuales (una fila por punto de copia): datastore, tipo, VMID, identificador del snapshot (formato ISO YYYY-MM-DDTHH:MM:SSZ), fecha local y tamaño.
crad-pbs-mgr.pyc --list-snapshots --vmid 167
Nota: tanto
--list-backupscomo--list-snapshotsobtienen los datos escaneando el layout en disco del datastore (<datastore>/ct|vm|host/<vmid>/<snapshot>/...), por lo que reflejan exactamente lo que hay almacenado, independientemente de las tareas que lo generaron.
6. Tareas (tasks) y logs
PBS registra cada operación (backup, verificación, sincronización, recolección de basura, etc.) como una tarea identificada por un UPID.
6.1. --list-tasks
Lista las tareas recientes del PBS. Respeta --limit, --task-type y --vmid. Para cada tarea muestra inicio, tipo, VMID, datastore, duración, estado y nodo.
crad-pbs-mgr.pyc --list-tasks --limit 50
crad-pbs-mgr.pyc --list-tasks --task-type syncjob --limit 50
Con -v (verbose) añade además el UPID completo de cada tarea, que es lo que se necesita para --task-status y --task-log.
6.2. --task-status UPID
Muestra el detalle de una tarea concreta a partir de su UPID: nodo, tipo, VMID, datastore, usuario, inicio/fin, estado y código de salida.
crad-pbs-mgr.pyc --task-status 'UPID:pbsserver:...:backup:...:root@pam:'
6.3. --task-log UPID
Imprime el log completo (texto) de una tarea concreta.
crad-pbs-mgr.pyc --task-log 'UPID:pbsserver:...:backup:...:root@pam:'
6.4. --last-backup-log --vmid VMID
Atajo muy útil: localiza la tarea de backup más reciente de un VMID y muestra su cabecera (datastore, tipo, snapshot, inicio/fin, estado, UPID) seguida del log completo. Evita tener que listar tareas y copiar UPIDs a mano.
crad-pbs-mgr.pyc --last-backup-log --vmid 167
7. Diagnóstico de una máquina (--diagnose --vmid VMID)
Responde a la pregunta “¿por qué esta VM/CT no se está respaldando últimamente?”. Reúne en un solo informe varias señales:
- Historial de snapshots (señal principal, obtenida del disco): número de copias, primera y última, tamaño total y un WARNING si han pasado demasiados días desde la última.
- Tareas relacionadas con ese VMID (backups y readers/verify) en el PBS.
- Jobs programados en el PBS que afectan a su datastore (sync / verify / prune), con su estado y horario.
-
Jobs de backup del PVE (
/etc/pve/jobs.cfg) y si el VMID está incluido en alguno, solo cuando se ejecuta en un host PVE.
crad-pbs-mgr.pyc --diagnose --vmid 167
Como la programación de los backups vive en el host PVE, el diagnóstico es más completo si se ejecuta en el nodo PVE propietario del invitado (o en un host que sea PBS y PVE a la vez). Si se ejecuta en un PBS puro, la herramienta lo indica y recomienda repetirlo en el PVE.
8. Jobs programados
8.1. Jobs del lado PBS
| Opción | Qué lista |
|---|---|
--list-sync-jobs |
Jobs de sincronización (incluye remoto y datastore remoto). |
--list-verify-jobs |
Jobs de verificación. |
--list-prune-jobs |
Jobs de poda/retención. |
Para cada job muestra id, horario (schedule), datastore, estado (habilitado/deshabilitado) y comentario.
crad-pbs-mgr.pyc --list-sync-jobs
crad-pbs-mgr.pyc --list-prune-jobs
8.2. Jobs del lado PVE: --list-backup-jobs
Lista los jobs de backup vzdump definidos en /etc/pve/jobs.cfg. Debe ejecutarse en un host PVE (es ahí donde reside esa configuración). Muestra id, horario, storage destino, VMIDs (o all), pool y estado.
crad-pbs-mgr.pyc --list-backup-jobs
9. Auditoría de cobertura de backups
Es una de las capacidades más potentes de la herramienta: recorre todos los grupos de backup del PBS y marca aquellos cuyo último snapshot es más antiguo que un umbral, para detectar máquinas que han dejado de respaldarse silenciosamente.
9.1. --audit-coverage
crad-pbs-mgr.pyc --audit-coverage
crad-pbs-mgr.pyc --audit-coverage --days 3
El umbral se controla con --days N (por defecto 7). Cada grupo se clasifica por severidad en función de los días transcurridos desde su última copia, relativos al umbral:
| Severidad | Condición (con umbral = D días) |
|---|---|
| OK | menos de D días |
| WARNING | entre D y 2·D días |
| STALE | entre 2·D y 4·D días |
| CRITICAL | 4·D días o más |
| IGNORED | el grupo está en la lista de exclusiones (ver §9.3) |
El informe muestra los grupos marcados ordenados por antigüedad, una columna Scheduled (si el VMID figura en un job de backup del PVE) y un resumen final con los totales por severidad.
La columna Scheduled se rellena cruzando con /etc/pve/jobs.cfg. Si ese fichero no es accesible desde el host (PBS puro), la columna muestra ? y la herramienta sugiere ejecutar la auditoría en un nodo PVE.
9.2. Salida en JSON: --json
Con --json, la auditoría emite la misma estructura de datos en formato JSON, pensada para ser consumida por un checker de Core-Admin o por scripts externos (incluye threshold_days, groups, summary, scheduled_vmids e ignore_list).
crad-pbs-mgr.pyc --audit-coverage --json
9.3. Lista de exclusiones (ignore-list)
Algunas máquinas no deben generar alarma aunque lleven tiempo sin copia (máquinas dadas de baja, plantillas, entornos de pruebas…). Para eso existe una lista de exclusiones persistente, almacenada en una base de datos SQLite (/etc/core-admin/databases/pbs-coverage-ignore-db.sql).
| Opción | Acción |
|---|---|
--list-ignored |
Lista las entradas excluidas (datastore, tipo, VMID, motivo, quién y cuándo). |
--ignore-vmid VMID --reason "TEXTO" |
Añade un VMID a la lista. El motivo es obligatorio. Si no se indican --datastore/--type, se autodetectan a partir de sus snapshots. |
--unignore-vmid VMID |
Elimina un VMID de la lista (acotado por --datastore/--type si se indican). |
--show-ignored |
En --audit-coverage, incluye también los grupos excluidos en la salida. |
crad-pbs-mgr.pyc --ignore-vmid 142 --reason "VM dada de baja en mayo 2026"
crad-pbs-mgr.pyc --list-ignored
crad-pbs-mgr.pyc --unignore-vmid 142
Los grupos excluidos no cuentan como alarma en la auditoría, pero quedan registrados con su motivo, autor y fecha para mantener la trazabilidad.
10. Restauración de snapshots (--restore)
Permite restaurar un snapshot de un contenedor (LXC) o una máquina virtual (KVM). La restauración debe ejecutarse en un host Proxmox VE.
Parámetros obligatorios:
-
--type ct|vm: tipo de invitado. -
--vmid VMID: VMID de origen del backup. -
--snapshot ISO: identificador del snapshot (p. ej.2026-04-28T03:56:37Z). -
--datastore NAME: id del storage tal y como lo conoce PVE.
Parámetros opcionales:
-
--target-vmid VMID: VMID destino (por defecto, el de origen). -
--target-storage STORAGE: storage destino en el host PVE. -
--force: sobrescribe un VMID existente (se pasa apct/qmrestore).
crad-pbs-mgr.pyc --restore --type ct --vmid 167 \
--snapshot 2026-04-28T03:56:37Z --datastore backup --target-vmid 9167
Comportamiento según el rol del host:
- En un host PVE, construye el comando
pct restore(LXC) oqmrestore(KVM), pide confirmación (salvo-y) y lo ejecuta. - En un PBS puro, no ejecuta nada: imprime el comando exacto que habría que lanzar en el nodo PVE. Funciona así como modo de inspección seguro.
11. Mantenimiento: purga de logs de tareas (--purge-task-logs)
PBS guarda un fichero de log por cada tarea bajo /var/log/proxmox-backup/tasks/, repartidos en 256 subdirectorios (00…ff). Con el tiempo, en servidores con muchas tareas, estos logs pueden llenar la partición /. Esta opción los purga de forma segura.
| Opción | Significado |
|---|---|
--purge-task-logs |
Borra los ficheros de log de tareas más antiguos que el umbral. |
--older-than-days N |
Umbral de antigüedad en días. Valor por defecto recomendado: 90. |
--task-log-dir DIR |
Directorio de logs de tareas (por defecto /var/log/proxmox-backup/tasks). |
--dry-run |
Previsualiza qué se borraría, sin eliminar nada. |
# 1) Previsualizar siempre primero
crad-pbs-mgr.pyc --purge-task-logs --dry-run
# 2) Ajustar el umbral si hace falta
crad-pbs-mgr.pyc --purge-task-logs --older-than-days 30 --dry-run
# 3) Ejecutar el borrado (pide confirmación; -y para omitirla)
crad-pbs-mgr.pyc --purge-task-logs --older-than-days 30
Garantías de seguridad del purgado:
- Solo actúa sobre los subdirectorios de buckets (
00…ff). Nunca toca los ficheros de nivel superior que gestiona PBS (active,index,archive*). - La antigüedad de cada log se determina a partir de la marca de tiempo de inicio codificada en el UPID del propio nombre del fichero (más fiable que el
mtime); si el nombre no es un UPID reconocible, se usa elmtimecomo respaldo. -
Nunca borra logs de tareas activas: lee
tasks/activey los excluye. - Antes de borrar, muestra el número de ficheros y el espacio que se liberará, y pide confirmación. Con
--dry-runsolo lista (las primeras 50 líneas, o todas con-v). - Deja traza de la operación en el log de Core-Admin (
report.log).
Arreglo de raíz recomendado: para que PBS rote estos logs por sí mismo y no haya que purgarlos a mano, conviene fijar la retención nativa en el
node.cfgdel PBS, por ejemplo:proxmox-backup-manager node update --task-log-max-days 30(verifica el nombre exacto del flag con
proxmox-backup-manager node update --helpsegún tu versión). El purgado de la herramienta sigue siendo útil como red de seguridad o para una limpieza puntual cuando el disco ya está lleno.
12. Modificadores de salida
| Opción | Efecto |
|---|---|
-v, --verbose
|
Salida detallada (p. ej. UPIDs en --list-tasks, listado completo en --purge-task-logs --dry-run). |
--debug |
Salida de depuración (implica --verbose). |
-y, --yes
|
Omite las preguntas de confirmación (restauración, purgado). |
13. Resumen de todas las opciones
| Categoría | Opción | Descripción breve |
|---|---|---|
| Inventario | --list-datastores |
Lista los datastores configurados. |
| Inventario | --list-backups |
Grupos de backup (una fila por VMID). |
| Inventario | --list-snapshots |
Snapshots individuales. |
| Tareas | --list-tasks |
Tareas recientes del PBS. |
| Tareas | --task-status UPID |
Detalle de una tarea. |
| Tareas | --task-log UPID |
Log completo de una tarea. |
| Tareas | --last-backup-log |
Log del último backup de --vmid. |
| Diagnóstico | --diagnose |
Por qué --vmid no se respalda. |
| Jobs | --list-sync-jobs |
Jobs de sincronización (PBS). |
| Jobs | --list-verify-jobs |
Jobs de verificación (PBS). |
| Jobs | --list-prune-jobs |
Jobs de poda/retención (PBS). |
| Jobs | --list-backup-jobs |
Jobs vzdump (PVE, /etc/pve/jobs.cfg). |
| Auditoría | --audit-coverage |
Marca grupos sin copia reciente. |
| Auditoría | --days N |
Umbral de la auditoría (por defecto 7). |
| Auditoría | --show-ignored |
Incluye los excluidos en la auditoría. |
| Auditoría | --json |
Salida de la auditoría en JSON. |
| Exclusiones | --list-ignored |
Lista las entradas excluidas. |
| Exclusiones | --ignore-vmid VMID |
Excluye un VMID (requiere --reason). |
| Exclusiones | --unignore-vmid VMID |
Quita un VMID de la lista. |
| Exclusiones | --reason TEXTO |
Motivo de la exclusión (obligatorio). |
| Restauración | --restore |
Restaura un snapshot (host PVE). |
| Restauración | --snapshot ISO |
Snapshot a restaurar. |
| Restauración | --target-vmid VMID |
VMID destino. |
| Restauración | --target-storage STORAGE |
Storage destino. |
| Restauración | --force |
Sobrescribe un VMID existente. |
| Mantenimiento | --purge-task-logs |
Purga logs de tareas antiguos. |
| Mantenimiento | --older-than-days N |
Umbral de antigüedad (por defecto 90). |
| Mantenimiento | --task-log-dir DIR |
Directorio de logs de tareas. |
| Mantenimiento | --dry-run |
Previsualiza el purgado. |
| Filtros |
--vmid / --type / --datastore
|
Filtros comunes. |
| Filtros |
--limit N / --task-type
|
Filtros de tareas. |
| Salida |
-v / --debug / -y
|
Verbose / depuración / sin confirmación. |
14. Ejemplos prácticos
Foto rápida del estado de los backups:
crad-pbs-mgr.pyc --list-backups
Detectar máquinas sin copia en los últimos 3 días:
crad-pbs-mgr.pyc --audit-coverage --days 3
Investigar por qué una CT no se respalda y ver su último log de backup:
crad-pbs-mgr.pyc --diagnose --vmid 167
crad-pbs-mgr.pyc --last-backup-log --vmid 167
Liberar espacio en / cuando se llena de logs de tareas:
crad-pbs-mgr.pyc --purge-task-logs --dry-run
crad-pbs-mgr.pyc --purge-task-logs --older-than-days 30
Restaurar un contenedor en un VMID nuevo (en el host PVE):
crad-pbs-mgr.pyc --restore --type ct --vmid 167 \
--snapshot 2026-04-28T03:56:37Z --datastore backup --target-vmid 9167
15. Preguntas frecuentes
P: ¿La herramienta modifica algo en el PBS?
Por defecto no. Solo modifican el sistema --restore, --purge-task-logs y la gestión de la lista de exclusiones (--ignore-vmid/--unignore-vmid). Las operaciones destructivas piden confirmación salvo que se use -y.
P: ¿Por qué --audit-coverage muestra ? en la columna Scheduled?
Porque la programación de los backups vive en /etc/pve/jobs.cfg, en el host PVE, y ese fichero no es accesible desde un PBS puro. Ejecuta la auditoría en un nodo PVE (o copia/monta ese fichero) para rellenar la columna.
P: ¿Es seguro --purge-task-logs? ¿Puede romper la lista de tareas de la interfaz de PBS?
Solo borra los ficheros de log por tarea de los buckets 00…ff, nunca el índice (index/archive*) ni las tareas activas. La interfaz de PBS seguirá listando las tareas; como mucho, al abrir el log de una tarea muy antigua ya purgada, no encontrará su texto. Usa --dry-run para ver exactamente qué se borraría.
P: ¿Por qué la restauración no hace nada en mi PBS?
Porque la restauración debe ejecutarse en un host Proxmox VE. En un PBS puro, la herramienta solo imprime el comando pct restore/qmrestore que tendrías que lanzar en el nodo PVE correspondiente.
P: ¿Cada cuánto debería purgar los logs de tareas?
Lo ideal es no tener que hacerlo a mano: fija task-log-max-days en el node.cfg del PBS para que se roten solos. El purgado de la herramienta queda como red de seguridad o para limpiezas puntuales (por ejemplo, cuando el disco ya está al límite).