Proxmox “pve-apt-hook failed”: por qué se bloquean las actualizaciones y cómo desbloquearlas de forma segura

Qué hace realmente “pve-apt-hook”

Proxmox VE se asienta sobre Debian, pero no es “solo Debian con una interfaz web”. Es un host de virtualización con opiniones: sobre kernels, repositorios, coherencia de clúster, cargadores de arranque y orden de empaquetado. Esas opiniones están codificadas en herramientas, y una de esas herramientas es un conjunto de hooks APT distribuidos por los paquetes de Proxmox (habitualmente vía pve-manager y afines).

Los hooks de APT son scripts que se ejecutan antes o después de operaciones de paquetes: piensa en “comprobaciones previas” y “limpieza posterior”. Proxmox los usa para prevenir una clase de trampas comunes en hipervisores:

• Mezclar suites de Debian o repositorios de Proxmox de formas que produzcan sistemas Frankenstein.
• Actualizar a un kernel o situación de cargador de arranque desde la cual el nodo no pueda reiniciar limpiamente.
• Dejar que nodos del clúster deriven en versiones principales diferentes y luego sorprenderse cuando corosync o las expectativas de la API difieran.
• Romper pilas de almacenamiento (ZFS, bibliotecas cliente de Ceph) actualizando piezas en el orden incorrecto.
• Instalar paquetes que entren en conflicto con meta-paquetes de Proxmox (como los meta-paquetes de kernel).

Cuando un hook sale con código distinto de cero, APT lo trata como un fallo crítico y se detiene. Por eso ves actualizaciones “bloqueadas” aunque el grafo de dependencias esté bien. El cortafuegos se activó.

Dos consecuencias operativas importantes:

1. El fallo del hook suele ser un síntoma, no la enfermedad. Arregla la desalineación subyacente (repos, estado de paquetes, bloqueo de dpkg, configuración) y el hook dejará de quejarse.
2. Eludir el hook es el último recurso. Puedes sortear los hooks de APT, pero entonces eres responsable de lo que el hook intentaba evitar—posiblemente a las 2 a.m. tras un reinicio.

Idea parafraseada (Gene Kranz): Failure is not an option — no como fanfarronería, sino como disciplina: diseñas sistemas que no aceptan fallos evitables.

Por qué se bloquean las actualizaciones: modos reales de fallo

1) Confusiones de repositorios: enterprise vs no-subscription, suite incorrecta, major equivocado

El disparador más común es la inconsistencia de repositorios. APT está feliz de calcular una ruta de actualización a través de repos mezclados. Proxmox, con prudencia, está menos entusiasmado. Problemas típicos:

• Habilitar pve-enterprise sin suscripción, lo que devuelve HTTP 401/403 o errores de “no firmado”.
• Tener habilitados tanto pve-enterprise como pve-no-subscription, produciendo caos de pinning.
• Usar una suite de Debian que no coincide con tu major de Proxmox (por ejemplo, mover Debian a trixie mientras sigues en un major de Proxmox que espera bookworm).
• Copiar y pegar una lista de fuentes desde un post en un blog escrito para otra versión de Proxmox.

2) Estado dañado de APT/dpkg: instalaciones interrumpidas, paquetes medio configurados

Si dpkg se interrumpió o un script post-install falló, los hooks de Proxmox tienden a bloquear más actualizaciones “normales” hasta que el estado del empaquetado vuelva a ser coherente. APT llama a esto “half-installed” o “not fully installed or removed”. Proxmox lo llama “no, hoy no”.

3) Retenciones de paquetes y kernels bloqueados

Las actualizaciones de kernel no son como actualizar htop. Un paquete de kernel retenido, un pve-kernel-* en hold, o un meta-paquete desalineado puede crear una situación en la que Proxmox intenta mantenerte en las rutas de kernel soportadas. El hook bloquea cuando detecta que vas a desviarte del camino previsto.

4) Problemas del cargador de arranque / EFI, especialmente tras cambios en el esquema de discos

Algunos sistemas actualizan bien y solo fallan después del reinicio—por eso Proxmox es conservador aquí. Si tienes un ESP mal montado, falta /boot/efi o /boot sin espacio, las actualizaciones que instalan kernels y initramfs se vuelven riesgosas.

5) Desalineación de versión en clúster y majors mixtos

En un clúster, “actualizar solo un nodo” puede ser válido, pero actualizar entre majors requiere planificación. Los hooks son una de las formas en que Proxmox te empuja a evitar saltos accidentales de major.

6) Acoplamiento estrecho de la pila de almacenamiento: ZFS y Ceph

Los nodos Proxmox a menudo ejecutan ZFS o clientes Ceph (o ambos). Actualizar bibliotecas, módulos de kernel o herramientas de usuario fuera de orden puede romper importaciones, flags de pool o compatibilidad cliente. Los hooks no solucionan todo eso, pero reducen la probabilidad de hacer algo evidentemente inseguro.

Broma #1: Un hook de APT es como un oficial de seguridad con casco: molesto hasta el momento en que te salva de caer en un hoyo que tú mismo cavaste.

Guion de diagnóstico rápido

Cuando aparece el error, no empieces a “arreglar” editando archivos al azar. Haz la evaluación rápida en orden. Buscas el primer cuello de botella que explique el fallo del hook.

Primero: ¿APT está sano y los repositorios son accesibles?

• Ejecuta apt update y lee el primer error, no el último.
• Busca 401/403, “Release file”, “not signed”, errores TLS, problemas DNS.
• Confirma que solo el repositorio de Proxmox previsto está habilitado (enterprise o no-subscription, no ambos).

Segundo: ¿dpkg está en estado limpio?

• Comprueba si dpkg --configure -a informa problemas.
• Verifica paquetes en hold (apt-mark showhold).
• Revisa dependencias rotas (apt -f install).

Tercero: ¿el bloqueo es por kernels/arranque?

• Comprueba espacio libre en /boot y /boot/efi.
• Confirma qué kernel está en ejecución y qué kernels están instalados.
• En root sobre ZFS, confirma que el estado de proxmox-boot-tool es sano (si aplica).

Cuarto: consideraciones de clúster

• Si estás en clúster, verifica si vas a hacer un upgrade mayor y si otros nodos están en un major diferente.
• Revisa la salud del quorum de corosync antes de tocar paquetes.

Tareas prácticas: comandos, salidas y decisiones

Estas son tareas reales que puedes ejecutar en un nodo Proxmox. Cada una incluye lo que implica la salida y qué decisión tomar a continuación. Hazlas en este orden aproximado a menos que ya conozcas la causa probable.

Task 1: reproducir el fallo con el máximo contexto

cr0x@server:~$ apt-get -o Debug::pkgProblemResolver=yes -o Debug::Acquire::https=true dist-upgrade
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Starting pkgProblemResolver with broken count: 0
...
E: Sub-process /usr/share/proxmox-ve/pve-apt-hook returned an error code (1)
E: Failure running hook scripts.

Qué significa: Confirmaste que es una salida del hook, no un problema del resolvedor. La salida de depuración alrededor del fallo puede mostrar qué comprobación activó el error.

Decisión: Revisa los logs/mensajes del hook específico, luego valida repos y estado de dpkg.

Task 2: comprobar el hook exacto y el paquete propietario

cr0x@server:~$ dpkg -S /usr/share/proxmox-ve/pve-apt-hook
pve-manager: /usr/share/proxmox-ve/pve-apt-hook

Qué significa: El hook proviene de pve-manager. Ese es tu paquete de plano de control, y está avisando a propósito.

Decisión: No lo borres. Averigua por qué está descontento.

Task 3: ejecutar APT update y leer errores como un SRE

cr0x@server:~$ apt update
Hit:1 http://deb.debian.org/debian bookworm InRelease
Hit:2 http://security.debian.org/debian-security bookworm-security InRelease
Err:3 https://enterprise.proxmox.com/debian/pve bookworm InRelease
  401  Unauthorized [IP: 51.91.38.34 443]
Reading package lists... Done
E: Failed to fetch https://enterprise.proxmox.com/debian/pve/dists/bookworm/InRelease  401  Unauthorized
E: The repository 'https://enterprise.proxmox.com/debian/pve bookworm InRelease' is not signed.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.

Qué significa: Repo enterprise habilitado sin credenciales/suscripción. APT lo está deshabilitando; el hook de Proxmox suele bloquear actualizaciones cuando la configuración de repos es inconsistente.

Decisión: O bien añade acceso enterprise correcto o deshabilita el repo enterprise y habilita el repo no-subscription (y hazlo limpiamente).

Task 4: inspeccionar las listas de fuentes de Proxmox y Debian

cr0x@server:~$ grep -R --line-number -E 'proxmox|pve|ceph' /etc/apt/sources.list /etc/apt/sources.list.d/*.list
/etc/apt/sources.list.d/pve-enterprise.list:1:deb https://enterprise.proxmox.com/debian/pve bookworm pve-enterprise
/etc/apt/sources.list.d/pve-no-subscription.list:1:deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription
/etc/apt/sources.list.d/ceph.list:1:deb http://download.proxmox.com/debian/ceph-quincy bookworm no-subscription

Qué significa: Están habilitados tanto enterprise como no-subscription. Es como poner dos volantes diferentes en el mismo coche.

Decisión: Elige un canal de repositorios de Proxmox. Si no tienes suscripción, deshabilita pve-enterprise.list.

Task 5: deshabilitar el repo incorrecto (de forma segura y auditable)

cr0x@server:~$ sed -i 's/^deb /# deb /' /etc/apt/sources.list.d/pve-enterprise.list
cr0x@server:~$ apt update
Hit:1 http://deb.debian.org/debian bookworm InRelease
Hit:2 http://security.debian.org/debian-security bookworm-security InRelease
Hit:3 http://download.proxmox.com/debian/pve bookworm InRelease
Hit:4 http://download.proxmox.com/debian/ceph-quincy bookworm InRelease
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
All packages are up to date.

Qué significa: Ahora APT ve repos coherentes. Eliminaste una fuente previsible de fallo.

Decisión: Reintenta la actualización. Si el hook aún falla, pasa a la integridad de dpkg.

Task 6: confirmar que dpkg no esté medio roto

cr0x@server:~$ dpkg --audit
The following packages are only half configured, probably due to problems configuring them the first time.
 pve-manager

Qué significa: Tienes una configuración interrumpida. Eso puede causar fallos del hook, porque los paquetes de Proxmox dependen de scripts postinst.

Decisión: Termina la configuración antes de intentar más actualizaciones.

Task 7: finalizar la configuración pendiente de paquetes

cr0x@server:~$ dpkg --configure -a
Setting up pve-manager (8.2.2) ...
Job for pveproxy.service failed because the control process exited with error code.
See "systemctl status pveproxy.service" and "journalctl -xeu pveproxy.service" for details.
dpkg: error processing package pve-manager (--configure):
 installed pve-manager package post-installation script subprocess returned error exit status 1
Errors were encountered while processing:
 pve-manager

Qué significa: Ahora tienes la causa concreta: pveproxy no arranca, por lo que la configuración de pve-manager falla.

Decisión: Deja de perseguir APT. Arregla la falla del servicio (a menudo certificados, puertos o configuración).

Task 8: inspeccionar la unidad systemd fallida y los logs

cr0x@server:~$ systemctl status pveproxy.service --no-pager
● pveproxy.service - PVE API Proxy Server
     Loaded: loaded (/lib/systemd/system/pveproxy.service; enabled; preset: enabled)
     Active: failed (Result: exit-code) since Thu 2025-12-26 09:41:12 UTC; 15s ago
    Process: 18722 ExecStart=/usr/bin/pveproxy start (code=exited, status=255/EXCEPTION)
...
cr0x@server:~$ journalctl -xeu pveproxy.service --no-pager | tail -n 20
Dec 26 09:41:12 server pveproxy[18722]: can't open certificate '/etc/pve/local/pve-ssl.pem': No such file or directory
Dec 26 09:41:12 server systemd[1]: pveproxy.service: Main process exited, code=exited, status=255/EXCEPTION

Qué significa: Falta el certificado SSL en /etc/pve. Eso es territorio del sistema de ficheros de clúster. O bien pmxcfs está inestable, o los archivos fueron eliminados.

Decisión: Valida la salud de pve-cluster/pmxcfs y regenera certificados si procede.

Task 9: comprobar el estado de pmxcfs (sistema de ficheros del clúster)

cr0x@server:~$ systemctl status pve-cluster --no-pager
● pve-cluster.service - The Proxmox VE cluster filesystem
     Loaded: loaded (/lib/systemd/system/pve-cluster.service; enabled; preset: enabled)
     Active: active (running) since Thu 2025-12-26 09:39:01 UTC; 2min 34s ago
cr0x@server:~$ ls -l /etc/pve/local/ | head
total 8
-rw-r----- 1 root www-data  428 Dec 26 09:39 pve-ssl.key
-rw-r----- 1 root www-data  0 Dec 26 09:39 pve-ssl.pem

Qué significa: El PEM existe pero tiene tamaño cero. Eso hará que pveproxy explote.

Decisión: Regenera certificados (idealmente de forma controlada y consciente de las implicaciones de clúster).

Task 10: regenerar certificados del nodo Proxmox

cr0x@server:~$ pvecm updatecerts --force
forcing certificate regeneration
writing new private key to '/etc/pve/local/pve-ssl.key'
writing new certificate to '/etc/pve/local/pve-ssl.pem'
Restarting pveproxy.service
Restarting pvedaemon.service

Qué significa: El certificado faltante/vacío se corrige y los servicios se reinician. Esto suele ser suficiente para que pve-manager termine de configurarse.

Decisión: Ejecuta de nuevo dpkg --configure -a y reintenta la actualización. Si esto es un clúster, entiende la distribución de certificados y la identidad del nodo.

Task 11: verificar la salud de los servicios tras la corrección

cr0x@server:~$ systemctl is-active pveproxy pvedaemon
active
active

Qué significa: El plano de control volvió. Ahora los scripts postinst de paquetes tienen una oportunidad de completarse.

Decisión: Reanuda la configuración de dpkg y las actualizaciones.

Task 12: identificar paquetes en hold (saboteadores silenciosos)

cr0x@server:~$ apt-mark showhold
pve-kernel-6.2.16-20-pve

Qué significa: Un paquete de kernel está en hold. A veces es intencional (pruebas de compatibilidad hardware). Otras veces es cinta adhesiva olvidada.

Decisión: Si no tienes una razón documentada para mantenerlo, quítale el hold. Si la tienes, espera que el hook se queje cuando los meta-paquetes no puedan progresar.

Task 13: quitar el hold con intención y luego previsualizar los cambios

cr0x@server:~$ apt-mark unhold pve-kernel-6.2.16-20-pve
Canceled hold on pve-kernel-6.2.16-20-pve.
cr0x@server:~$ apt-get -s dist-upgrade | sed -n '1,40p'
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Calculating upgrade... Done
The following packages will be upgraded:
  pve-kernel-6.5.13-5-pve pve-kernel-helper proxmox-ve
...

Qué significa: La simulación muestra una ruta normal de kernel/meta. No hay sorpresas como la eliminación de la mitad del sistema.

Decisión: Procede cuando la ventana de mantenimiento permita un reinicio (las actualizaciones de kernel importan).

Task 14: comprobar espacio en particiones de arranque antes de instalar kernels

cr0x@server:~$ df -h /boot /boot/efi
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda2       512M  486M   26M  95% /boot
/dev/sda1       512M  110M  402M  22% /boot/efi

Qué significa: /boot está casi lleno. Las instalaciones de kernel pueden fallar a mitad de camino, dejando dpkg roto y (peor) confusión en el cargador de arranque.

Decisión: Limpia kernels antiguos antes de actualizar, pero hazlo con cuidado para mantener al menos un kernel conocido como bueno.

Task 15: listar kernels instalados y eliminar los antiguos de forma segura

cr0x@server:~$ dpkg -l 'pve-kernel-*' | awk '/^ii/{print $2,$3}'
pve-kernel-6.2.16-20-pve 6.2.16-20
pve-kernel-6.2.16-22-pve 6.2.16-22
pve-kernel-6.5.13-5-pve 6.5.13-5
cr0x@server:~$ uname -r
6.2.16-22-pve
cr0x@server:~$ apt-get remove pve-kernel-6.2.16-20-pve
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following packages will be REMOVED:
  pve-kernel-6.2.16-20-pve
After this operation, 380 MB disk space will be freed.
Do you want to continue? [Y/n] y

Qué significa: Eliminaste un kernel más antiguo que no está en ejecución. Liberar espacio reduce el riesgo en la actualización.

Decisión: Mantén el kernel en ejecución y un kernel de recuperación. Luego procede con la actualización.

Task 16: verificar la política de paquetes y prioridades de repos (comprobación de pinning)

cr0x@server:~$ apt-cache policy pve-manager proxmox-ve | sed -n '1,80p'
pve-manager:
  Installed: 8.2.2
  Candidate: 8.2.2
  Version table:
 *** 8.2.2 500
        500 http://download.proxmox.com/debian/pve bookworm/pve-no-subscription amd64 Packages
        100 /var/lib/dpkg/status
proxmox-ve:
  Installed: 8.2-1
  Candidate: 8.2-1
  Version table:
 *** 8.2-1 500
        500 http://download.proxmox.com/debian/pve bookworm/pve-no-subscription amd64 Packages
        100 /var/lib/dpkg/status

Qué significa: Los candidatos provienen del repo esperado. Si los candidatos provinieran de orígenes inesperados, esperaría fricción del hook y actualizaciones extrañas.

Decisión: Procede. Si los candidatos parecen incorrectos, arregla fuentes/pinning primero.

Task 17: hacer la actualización real en un entorno controlado

cr0x@server:~$ apt-get dist-upgrade
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Calculating upgrade... Done
...
Setting up proxmox-ve (8.2-1) ...
Processing triggers for pve-ha-manager (4.0.5) ...
Processing triggers for initramfs-tools (0.142) ...
update-initramfs: Generating /boot/initrd.img-6.5.13-5-pve

Qué significa: Los scripts postinst y los triggers de initramfs se ejecutaron correctamente—aquí es donde muchos sistemas rotos mueren.

Decisión: Planifica el reinicio. No “reinicies más tarde” y luego lo olvides por 90 días.

Task 18: confirmar que el hook ya no bloquea y revisar reinicios pendientes

cr0x@server:~$ pveversion -v
proxmox-ve: 8.2-1 (running kernel: 6.2.16-22-pve)
pve-manager: 8.2.2 (running version: 8.2.2)
...
cr0x@server:~$ ls -l /var/run/reboot-required 2>/dev/null || echo "no reboot flag"
-rw-r--r-- 1 root root 0 Dec 26 10:12 /var/run/reboot-required

Qué significa: Actualizaste paquetes pero todavía estás ejecutando un kernel antiguo. La bandera de reinicio es tu recordatorio de que la realidad no se ha puesto al día.

Decisión: Reinicia durante la ventana y luego valida el nuevo kernel y la salud del almacenamiento.

Tres microhistorias corporativas desde el campo

Incidente #1 (suposición errónea): “Es Debian, así que se comportará como Debian.”

Un equipo ejecutaba un clúster Proxmox modesto que albergaba cargas “solo internas”. La lógica empresarial fue clásica: si es interno, no es crítico; si no es crítico, puedes improvisar. Tenían un playbook estándar de Debian para actualizaciones y decidieron que Proxmox podría seguirlo.

La suposición errónea apareció en la configuración de repos. Alguien habilitó el repositorio enterprise porque sonaba “más estable”, pero no había suscripción. apt update empezó a lanzar errores de autenticación. Vieron los errores, se encogieron de hombros y ejecutaron apt dist-upgrade de todos modos. El hook lo bloqueó. Se lo tomaron a mal.

Para “arreglarlo”, comentaron el hook en la configuración de APT (no recomendado, y sí, fue tan feo como suena). La actualización continuó, pero en el proceso tiró un conjunto de paquetes de Debian que no estaban alineados con el conjunto previsto de Proxmox. No hubo un fallo inmediato—solo una deriva silenciosa.

Un mes después reiniciaron el nodo por mantenimiento de hardware no relacionado. El arranque se realizó con un kernel que no tenía el módulo ZFS alineado. La importación falló. No tenían un kernel de recuperación limpio porque los kernels antiguos se habían autoremovido durante el “arreglo” anterior. La caída no fue dramática; fue peor—lenta, confusa y llena de síntomas contradictorios.

La conclusión del postmortem fue contundente: el hook tenía razón. No intentaba arruinarles el día. Intentaba evitar que actualizaran sobre una base de repos incoherente. Rehicieron su proceso: política de repos explícita por entorno, comprobaciones de origen de paquetes y una regla estricta de que si Proxmox bloquea una actualización, lo trates como un diagnóstico, no como un obstáculo.

Incidente #2 (optimización que salió mal): “Aceleremos actualizaciones limpiando agresivamente.”

Otra organización tenía ventanas de mantenimiento estrictas. Su proyecto de optimización fue simple: acelerar actualizaciones reduciendo el bloat del disco. Un ingeniero con buenas intenciones añadió un cron para purgar kernels antiguos y limpiar caches de paquetes de forma más agresiva que los valores por defecto.

Funcionó—hasta que dejó de hacerlo. Un nodo tenía una partición /boot algo más pequeña (imagen legacy, nunca estandarizada). Los paquetes de kernel se acumularon con el tiempo. El cron eliminó kernels antiguos, pero lo hizo sin conciencia de “conservar un kernel de fallback”. Además se ejecutó cerca de la hora de la actualización.

Durante una actualización rutinaria, initramfs-tools intentó generar un nuevo initrd y se quedó sin espacio a mitad de escritura. Ese es el tipo especial de fallo que deja a dpkg medio configurado y tus artefactos de arranque inconsistentes. Los hooks de APT empezaron a bloquear más actualizaciones porque el estado del empaquetado estaba roto.

Lo desbloquearon limpiando más (por supuesto), lo que removió el último kernel conocido como bueno. El nodo reinició en un estado donde el hipervisor arrancó pero la red era inestable por incompatibilidades de drivers. Las VMs migraron lentamente y la reparación requirió manos locales y un arranque de rescate.

La lección no fue “no limpiar”. La lección fue “no limpiar a ciegas”. La higiene de disco es buena, pero el ciclo de vida de los kernels en hipervisores debe ser intencional: preserva un fallback, confirma espacio de arranque y trata la generación de initramfs como un paso de ruta crítica, no como un artefacto de mejor esfuerzo.

Incidente #3 (práctica aburrida pero correcta): staging, simulación y un kernel extra salvaron el día

Un tercer equipo gestionaba un clúster de cargas mixtas: bases de datos con estado, servicios web sin estado, algunos appliances raros y unos hosts con passthrough de GPU que todos temían tocar. Su proceso era poco glamuroso: cada actualización empezaba con apt-get -s dist-upgrade, luego comprobaciones de origen de paquetes y un snapshot del estado de configuración.

También tenían un hábito que parecía paranoico pero era simplemente competente: siempre se aseguraban de que el kernel en ejecución siguiera instalado y de que existiera al menos un kernel más nuevo instalado antes de reiniciar. Sin excepciones, incluso si costaba unos cientos de megabytes.

Una semana, una actualización introdujo una regresión para un driver NIC específico en su hardware. El nodo reinició y quedó con red degradada—todavía accesible, pero no lo suficiente estable para tráfico de producción. Como mantuvieron el kernel anterior instalado, seleccionaron el kernel más antiguo desde el menú de arranque (consola remota vía IPMI). El nodo volvió a un comportamiento estable.

Pincharon el kernel problemático solo en esos hosts, documentaron la razón y esperaron la corrección posterior. El hook nunca fue el enemigo, porque el equipo no trató las actualizaciones como ruleta. La solución fue aburrida, y lo aburrido está subvalorado.

Broma #2: Lo único peor que una actualización fallida es una actualización “exitosa” que falla en el siguiente reinicio.

Errores comunes: síntomas → causa raíz → solución

1) Síntoma: “pve-apt-hook failed” justo después de habilitar un repo

Causa raíz: Repositorio enterprise habilitado sin suscripción, o ambos enterprise y no-subscription habilitados.

Solución: Habilita exactamente un canal de Proxmox. Comenta /etc/apt/sources.list.d/pve-enterprise.list si no tienes acceso; mantén pve-no-subscription si esa es tu política. Ejecuta apt update hasta que esté limpio.

2) Síntoma: la actualización falla, dpkg se queja de “post-installation script returned error”

Causa raíz: Un servicio de Proxmox (a menudo pveproxy, pvedaemon, pve-cluster) no puede arrancar por problemas de configuración/certificados.

Solución: Deja de ejecutar apt repetidamente. Inspecciona systemctl status y journalctl, arregla el servicio y luego ejecuta dpkg --configure -a.

3) Síntoma: “no hay suficiente espacio en /boot” durante la actualización, seguido de fallos del hook

Causa raíz: La instalación del kernel falló a mitad de camino, dejando dpkg en un estado roto; ejecuciones posteriores se encuentran con hooks y errores de empaquetado.

Solución: Libera espacio en /boot eliminando kernels antiguos que no estén en ejecución. Luego ejecuta apt -f install y dpkg --configure -a para reparar.

4) Síntoma: el hook falla tras intentos de “upgrade” de release de Debian

Causa raíz: Desajuste de suite de Debian con las expectativas de la release de Proxmox; puede que hayas mezclado bullseye/bookworm o similar entre fuentes.

Solución: Alinea las fuentes de Debian con la suite soportada para tu major de Proxmox. Si haces un upgrade mayor de Proxmox, sigue una secuencia de upgrade mayor, no un simple apt dist-upgrade.

5) Síntoma: la actualización quiere eliminar proxmox-ve o instalar kernels genéricos de Debian

Causa raíz: Conflictos de meta-paquetes, prioridades de repos equivocadas, o una eliminación accidental de meta-paquetes de Proxmox.

Solución: Inspecciona apt-cache policy proxmox-ve y asegura que los candidatos provengan de repos Proxmox. Reinstala el meta proxmox-ve si es necesario, y elimina meta-paquetes de kernel de Debian accidentales si están tomando control.

6) Síntoma: en sistemas con arranque ZFS, los kernels se instalan pero el nodo no arranca con el kernel nuevo

Causa raíz: Problemas de sincronización del cargador entre ESPs en espejo o proxmox-boot-tool no actualizado tras cambios en discos.

Solución: Valida proxmox-boot-tool status y re-inicializa/sincroniza según sea necesario antes de confiar en las actualizaciones de kernel.

7) Síntoma: nodos del clúster muestran candidatos de paquetes distintos y los fallos del hook aparecen solo en un nodo

Causa raíz: Fuentes específicas por nodo, pinning residual o una diferencia local en un proxy apt.

Solución: Haz un diff de /etc/apt y confirma que las definiciones de repos coincidan con la política del clúster. Estandariza pins y limpia listas obsoletas.

Listas de verificación / plan paso a paso

Cuando ves “pve-apt-hook failed” (nodo único)

1. Para. No repitas el mismo comando cinco veces. No vas a forzar un hook.
2. Ejecuta apt update y deja que esté limpio (sin errores de autenticación, sin Release faltantes).
3. Audita repos de Proxmox: exactamente uno de enterprise/no-subscription habilitado.
4. Ejecuta dpkg --audit. Si algo está medio configurado, arréglalo primero.
5. Ejecuta dpkg --configure -a y trata los fallos arreglando el servicio o archivo que causa el error postinst.
6. Revisa apt-mark showhold por holds que bloqueen meta-paquetes.
7. Comprueba espacio en disco en /boot y /var.
8. Simula la actualización (apt-get -s dist-upgrade) y asegúrate de que no esté eliminando proxmox-ve.
9. Procede con la actualización real.
10. Reinicia dentro de la ventana. Confirma que uname -r coincide con el nuevo kernel.

Postura de actualización segura para clúster (qué hacer antes de tocar paquetes)

1. Confirma quorum y salud de corosync. Un upgrade de clúster con quorum inestable es jugar a la ruleta.
2. Elige un orden: nodos no críticos primero, luego críticos, luego nodos “especiales” (GPU, HBA passthrough).
3. Migra o apaga VMs en el nodo que vas a actualizar. Si no puedes, no estás en ventana de mantenimiento; estás en una ventana de esperanza.
4. Haz snapshots de configuración: copia de seguridad de /etc y del estado de /etc/pve (al menos tarballs). En clúster, trata /etc/pve con cuidado.
5. Asegura al menos una entrada de arranque de fallback (kernel antiguo) instalada.

Qué evitar (porque “funciona” hasta que te arruina)

• No elimines ni bypasses los hooks APT de Proxmox como primera respuesta.
• No mezcles canales de repositorios “temporalmente”. Los cambios temporales de repos tienen una vida media larga.
• No actualices kernels cuando /boot esté lleno. Así es como creas corrupción de dpkg programada.
• No hagas upgrades de major simplemente con “apt dist-upgrade”. Los upgrades mayores merecen un plan y una historia de reversión.

Hechos interesantes y contexto histórico

• Hecho 1: El modelo de empaquetado de Proxmox VE usa deliberadamente meta-paquetes (como proxmox-ve) para mantener un conjunto coherente de kernel y componentes de userland alineados.
• Hecho 2: Los hooks de APT existen desde hace años como forma de extender el comportamiento de paquetes sin bifurcar APT; Proxmox usa ese mecanismo para hacer cumplir invariantes del sistema.
• Hecho 3: Proxmox VE se construye sobre Debian stable, que prioriza la estabilidad sobre la novedad—Proxmox selecciona luego kernels y componentes de virtualización más nuevos encima.
• Hecho 4: La división entre repos enterprise y no-subscription no es solo teatro de licencias; también trata del ritmo de actualizaciones y las expectativas de soporte.
• Hecho 5: Muchos nodos Proxmox arrancan desde ZFS (incluyendo setups de arranque en espejo), lo que complica la gestión de kernel/cargador comparado con una raíz ext4 única.
• Hecho 6: /etc/pve no es un directorio normal en setups de clúster; es un sistema de ficheros de clúster, y archivos faltantes ahí pueden ser síntoma de problemas de estado de clúster más profundos.
• Hecho 7: La acumulación de paquetes de kernel es un problema recurrente de ops porque los kernels son grandes, las imágenes initramfs son grandes y las particiones /boot suelen ser demasiado pequeñas por valores heredados.
• Hecho 8: Históricamente Proxmox soportó múltiples backends de almacenamiento (LVM, ZFS, Ceph), y la seguridad en actualizaciones debe tener en cuenta diferentes modos de fallo entre ellos.

Preguntas frecuentes

Q1: ¿Es “pve-apt-hook failed” un bug de APT o de Proxmox?

Por lo general ninguno de los dos. Es Proxmox devolviendo intencionalmente un código distinto de cero desde un hook APT porque detectó un estado riesgoso o inconsistente. Trátalo como una señal de violación de política.

Q2: ¿Puedo simplemente deshabilitar el hook para forzar la actualización?

Puedes, pero no deberías—a menos que sea una medida de emergencia controlada y bien entendida cuando tienes acceso a la consola y un plan de reversión. Si lo eludes casualmente, te apuntas a fallos de arranque, deriva de repos y sorpresas del tipo “por qué está rota la interfaz”.

Q3: Habilité pve-enterprise y ahora fallan las actualizaciones. ¿Cuál es la solución correcta?

Si tienes suscripción, mantenla y asegúrate de que las credenciales/acceso sean correctos. Si no, comenta el repo enterprise y habilita pve-no-subscription. Luego ejecuta apt update hasta que esté limpio.

Q4: ¿Por qué a Proxmox le importa tanto la consistencia de repos?

Porque los hipervisores son infraestructura. Los repos mezclados pueden producir un sistema que “funciona” hasta el siguiente reinicio, el siguiente kernel o la próxima vez que un servicio se reinicie. Proxmox prefiere fallar temprano mientras todavía tienes un nodo funcional.

Q5: El hook falla pero apt update está limpio. ¿Qué sigue?

Revisa el estado de dpkg (dpkg --audit), termina la configuración (dpkg --configure -a), comprueba paquetes en hold y confirma que /boot no esté lleno. Los fallos de hook a menudo siguen a daños en dpkg.

Q6: ¿Necesito reiniciar después de las actualizaciones?

Si se actualizaron el kernel o librerías de bajo nivel, sí. Puedes verificarlo con /var/run/reboot-required y comparando uname -r con los kernels instalados. Reiniciar más tarde está bien; olvidarlo para siempre no lo está.

Q7: ¿Cómo sé si una actualización intenta eliminar algo crítico?

Simúlalo: apt-get -s dist-upgrade. Si quiere eliminar proxmox-ve o instalar un meta-paquete de kernel genérico de Debian en lugar de kernels de Proxmox, detente y arregla tus fuentes/pinning.

Q8: ¿Este error afecta a Ceph o ZFS de forma diferente?

El hook en sí es general, pero las consecuencias no lo son. En arranque ZFS, la alineación kernel/módulo importa. Con Ceph, la compatibilidad de librerías cliente puede importar. En cualquier caso, mantiene actualizaciones coherentes y sigue una disciplina de reiniciar y validar.

Q9: ¿Por qué importa arreglar pveproxy para las actualizaciones de paquetes?

Porque los paquetes de Proxmox frecuentemente ejecutan scripts post-install que esperan que servicios centrales arranquen o que configuraciones se validen. Si postinst falla, dpkg queda roto y el hook probablemente seguirá bloqueando operaciones “normales” hasta que lo repares.

Próximos pasos que no te morderán después

Cuando Proxmox lanza pve-apt-hook failed, no está siendo dramático. Está haciendo cumplir invariantes: repos coherentes, estado de empaquetado consistente y resultados de kernel/arranque más seguros. Tu trabajo es encontrar qué invariante rompiste—y luego arreglar eso, no al mensajero.

Pasos prácticos siguientes:

1. Deja apt update limpio y asegura que solo esté habilitado el canal de repos de Proxmox previsto.
2. Repara el estado de dpkg (dpkg --audit, dpkg --configure -a) y arregla servicios fallidos en lugar de repetir las actualizaciones.
3. Verifica el espacio en /boot y elimina kernels antiguos con cuidado (mantén un fallback).
4. Simula actualizaciones antes de ejecutarlas y no ignores los reinicios planificados.
5. Para clústeres: confirma quorum, actualiza en orden y trata cada nodo como un sistema de producción—porque lo es.