Proxmox pveproxy.service falló: 7 causas comunes y el orden correcto de reparación

Guion de diagnóstico rápido (hacer esto primero)

Tu objetivo no es “reiniciar el servicio hasta que funcione”. Tu objetivo es identificar el cuello de botella en menos de cinco minutos:
¿es configuración, sistema de archivos, TLS, servicios de dependencia o estado del clúster?

Minuto 0–1: ¿solo es la interfaz web o el nodo está enfermo en serio?

• Confirma que puedes hacer SSH al host.
• Comprueba si las VMs están en ejecución (no asumas; compruébalo).
• Verifica si el puerto 8006 está escuchando localmente.

Minuto 1–2: Lee la razón real de la falla

• systemctl status pveproxy -l para la línea de error principal.
• journalctl -u pveproxy -b --no-pager para el contexto completo.

Minuto 2–3: Eliminaciones rápidas que resuelven la mitad de incidentes

• Disco lleno: df -h y df -i (ambos importan).
• Desfase horario: timedatectl (TLS odia los viajes en el tiempo).
• Saneamiento de hostname/IP: hostname -f, getent hosts $(hostname -f).

Minuto 3–5: Dependencias y sistema de archivos del clúster

• ¿Está pve-cluster arriba? ¿/etc/pve responde?
• ¿Está pvedaemon arriba? A menudo falla por la misma razón subyacente.
• Si está en clúster: revisa el estado de quorum/corosync antes de “arreglar” lo equivocado.

El orden importa porque algunas “soluciones” destruyen evidencia. Si reinicias primero, borras los logs más útiles y puedes convertir un
tropiezo recuperable de pmxcfs en un problema de split-brain en el clúster.

Hechos y contexto interesantes (por qué falla así)

• Hecho 1: pveproxy es un servicio en Perl que termina HTTPS para la interfaz web de Proxmox en el puerto 8006, y es exigente con certificados y permisos de archivos.
• Hecho 2: La configuración del clúster de Proxmox vive en /etc/pve, respaldada por pmxcfs (un sistema de archivos distribuido basado en FUSE). Si /etc/pve se queda atascado, muchos servicios “aleatorios” fallan.
• Hecho 3: Incluso en un “clúster” de un solo nodo (sí, existe eso), pmxcfs sigue presente. La gente lo olvida y lo diagnostica como “solo un servicio web”.
• Hecho 4: Los errores de TLS son desproporcionadamente comunes tras cambios de hostname porque Proxmox emite certificados de nodo ligados a esa identidad.
• Hecho 5: En sistemas basados en Debian, “disco lleno” puede manifestarse como fallos al escribir certificados, archivos PID y logs—así que el error que ves puede ser un síntoma secundario.
• Hecho 6: Los problemas de quorum de Corosync no siempre detienen las cargas de trabajo. Suelen detener primero las operaciones del plano de gestión, lo que hace que el outage parezca peor de lo que es.
• Hecho 7: Proxmox centraliza intencionalmente muchas configuraciones en /etc/pve para que los nodos del clúster converjan. Eso es excelente para operaciones—hasta que la tienda de configuración no está disponible.
• Hecho 8: Que el puerto 8006 esté caído no significa “Proxmox está caído”. En incidentes reales, las VMs siguen sirviendo tráfico mientras la gente entra en pánico por la falta de UI.
• Hecho 9: Muchos eventos de “service failed” son causados por algo externo al servicio: DNS, tiempo, sistema de archivos o una dependencia. Culpar a pveproxy es como culpar a la alarma de humo por la comida quemada.

El orden correcto para arreglar: deja de adivinar, empieza a acotar

Aquí está la secuencia opinada que minimiza el tiempo de inactividad y evita daños colaterales. Síguela incluso si “ya sabes” qué pasó.
A menudo te equivocas y los logs no mienten.

1. Estabiliza el acceso: haz SSH, confirma que estás en el nodo correcto y que las cargas de trabajo están bien.
2. Lee la razón de la falla: systemctl status y journalctl. No reinicies todavía.
3. Elimina “errores no forzados”: disco lleno, agotamiento de inodos, desfase horario, DNS/hostname inconsistente.
4. Revisa la salud del sistema de archivos del clúster: pve-cluster, la capacidad de respuesta de /etc/pve, el montaje FUSE.
5. Revisa material de certificados/llaves: existencia de archivos, permisos, caducidad y si la identidad del nodo cambió.
6. Valida conflictos de enlace de puerto: si algo más está usando 8006, o procesos residuales.
7. Sólo entonces reinicia servicios: reinicia en orden de dependencias y observa los logs mientras lo haces.

Una cita para mantenerte honesto. Werner Vogels (CTO de AWS) tiene una idea para ops que viene bien:
Todo falla, todo el tiempo; diseña y opera como si la falla fuera normal. — Werner Vogels (idea parafraseada)

Broma #1: Reiniciar primero es como “arreglar” la luz de aviso del coche quitando la bombilla. El tablero queda impecable; el motor no está de acuerdo.

7 causas comunes de pveproxy.service fallado (con la solución correcta)

Causa 1: Disco lleno (o agotamiento de inodos) rompe el plano de gestión

Si / está lleno, pveproxy no puede escribir logs, archivos PID ni temporales. Si los inodos están agotados, puedes tener “espacio libre”
pero no poder crear archivos. Ambos producen fallos que parecen TLS, permisos o caídas aleatorias de servicios.

Orden de arreglo: libera espacio de forma segura y luego reinicia los servicios. No borres archivos al azar en /etc/pve o /var/lib/pve-cluster.

• Limpia caches de apt, kernels antiguos (con cuidado), logs antiguos y backups fallidos.
• Revisa /var/log, /var/lib/vz, /rpool (ZFS) y cualquier target de backup montado.

Causa 2: Problemas de pmxcfs / pve-cluster (//etc/pve colgado)

Si /etc/pve está lento o atascado, los servicios que leen su configuración desde ahí se comportan mal. A veces se quedan colgados; otras veces salen.
Una pista clásica: comandos como ls /etc/pve se quedan bloqueados o pvecm status tarda una eternidad.

Orden de arreglo: inspecciona pve-cluster y el estado de corosync/quorum (si está en clúster), luego reinicia servicios de clúster con cuidado.

Causa 3: Problemas de certificados/llaves (caducados, ausentes, permisos o hostname no coincidente)

pveproxy es un endpoint HTTPS. Si el par de llaves falta, no es legible o refiere a una identidad que ya no coincide con el nodo,
puede fallar al iniciar o iniciarse pero presentar una UI rota/ en blanco según el comportamiento del cliente.

Orden de arreglo: valida archivos y permisos primero; regenera certificados solo si entiendes por qué fallaron.

Causa 4: Resolución de hostname y deriva de identidad del nodo

Proxmox es sensible a la identidad del nodo porque forma parte de la membresía del clúster, del nombre en los certificados y de las expectativas de la API.
Un cambio descuidado de hostname (o una caída de DNS) puede desencadenar “pveproxy falló” porque otros componentes se niegan a continuar con identidades inconsistentes.

Orden de arreglo: arregla /etc/hosts / DNS primero, luego los certificados y después los servicios.

Causa 5: Conflicto de enlace en el puerto 8006 o proceso zombi

A veces pveproxy no puede enlazar 8006 porque otro proceso lo está usando—a menudo un reverse proxy mal configurado, un servicio de prueba suelto
o una instancia previa que no salió correctamente.

Orden de arreglo: identifica el proceso que usa el puerto, deténlo o reconfigúralo, y luego inicia pveproxy.

Causa 6: Estado de paquete roto o actualizaciones parciales

Una actualización a medio terminar puede dejar módulos Perl, bibliotecas o archivos de configuración inconsistentes. El síntoma: pveproxy falla de inmediato
con errores de carga de módulos, o inicia pero lanza excepciones en tiempo de ejecución.

Orden de arreglo: confirma la salud de los paquetes, soluciona problemas de dpkg, reinstala los paquetes relevantes si hace falta y solo entonces reinicia.

Causa 7: Desfase horario y rarezas de TLS/cookies

Si el tiempo salta, los certificados parecen “aún no válidos” o “caducados”, las sesiones se comportan de forma extraña y los navegadores muestran errores que parecen bugs de UI.
Problemas de NTP también pueden coincidir con eventos de energía o deriva de tiempo en el host de virtualización.

Orden de arreglo: arregla la sincronización de tiempo primero. Regenerar certificados sin arreglar el tiempo es una buena forma de perder la tarde.

Broma #2: La deriva temporal es el único bug que puede hacer que tu certificado “caduque” en el futuro. Felicitaciones, inventaste la máquina del tiempo—desafortunadamente para TLS.

Tareas prácticas: comandos, salida esperada y la decisión que tomas

Estas son las tareas que realmente ejecuto. No porque sean elegantes, sino porque reducen rápido el espacio de búsqueda.
Cada tarea incluye: comando(s), qué significa la salida y qué decisión tomar después.

Tarea 1: Confirma el estado del servicio y captura la línea de error principal

cr0x@server:~$ systemctl status pveproxy -l
● pveproxy.service - PVE API Proxy Server
     Loaded: loaded (/lib/systemd/system/pveproxy.service; enabled)
     Active: failed (Result: exit-code) since Mon 2025-12-25 10:31:14 UTC; 2min 3s ago
    Process: 1234 ExecStart=/usr/bin/pveproxy start (code=exited, status=255/EXCEPTION)
   Main PID: 1234 (code=exited, status=255/EXCEPTION)

Dec 25 10:31:14 pve1 pveproxy[1234]: starting server
Dec 25 10:31:14 pve1 pveproxy[1234]: can't open certificate '/etc/pve/local/pve-ssl.pem': No such file or directory
Dec 25 10:31:14 pve1 systemd[1]: pveproxy.service: Main process exited, code=exited, status=255/EXCEPTION
Dec 25 10:31:14 pve1 systemd[1]: pveproxy.service: Failed with result 'exit-code'.

Significado: Esto no es “la UI está lenta”. Es una falla de arranque dura. La línea clave es el error de ruta de archivo.
Decisión: no toques puertos ni firewalls aún. Ve directamente a comprobar existencia de certificados/llaves y la salud de /etc/pve.

Tarea 2: Lee el journal completo de pveproxy para este arranque

cr0x@server:~$ journalctl -u pveproxy -b --no-pager -n 200
Dec 25 10:31:14 pve1 pveproxy[1234]: starting server
Dec 25 10:31:14 pve1 pveproxy[1234]: can't open certificate '/etc/pve/local/pve-ssl.pem': No such file or directory
Dec 25 10:31:14 pve1 systemd[1]: pveproxy.service: Main process exited, code=exited, status=255/EXCEPTION
Dec 25 10:31:14 pve1 systemd[1]: pveproxy.service: Failed with result 'exit-code'.

Significado: Confirma que es consistente y no intermitente.
Decisión: procede a comprobaciones de archivos y del sistema de archivos del clúster.

Tarea 3: Comprueba si algo está escuchando en el puerto 8006 localmente

cr0x@server:~$ ss -ltnp | grep -E ':8006\s'

Significado: La ausencia de salida típicamente significa que nada está escuchando. Si ves un proceso, puede que no sea pveproxy.
Decisión: si otra cosa ocupa 8006, salta a la ruta de conflicto de puerto; si no, céntrate en por qué pveproxy no arranca.

Tarea 4: Identifica el proceso si 8006 está ocupado

cr0x@server:~$ ss -ltnp | grep -E ':8006\s'
LISTEN 0      4096         0.0.0.0:8006      0.0.0.0:*    users:(("nginx",pid=2200,fd=12))

Significado: Nginx está en 8006. Eso casi siempre está mal en un nodo Proxmox salvo que hayas movido intencionalmente la UI.
Decisión: para o reconfigura nginx; libera 8006; luego inicia pveproxy.

Tarea 5: Comprueba espacio en disco y disponibilidad de inodos (ambos)

cr0x@server:~$ df -h /
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda2        28G   28G     0 100% /

cr0x@server:~$ df -i /
Filesystem     Inodes  IUsed   IFree IUse% Mounted on
/dev/sda2     1835008 250000 1585008   14% /

Significado: El espacio está al 100%. Los inodos están bien. Esto puede romper los arranques de servicios.
Decisión: libera espacio antes de hacer cualquier otra cosa. Reiniciar no ayudará; puede fallar aún más.

Tarea 6: Encuentra los mayores consumidores rápidamente (sin borrar a ciegas)

cr0x@server:~$ du -xhd1 /var | sort -h
1.2G    /var/cache
2.8G    /var/log
14G     /var/lib
18G     /var

Significado: El mayor uso está bajo /var/lib (a menudo imágenes, backups o BD del clúster) y logs.
Decisión: revisa /var/log por procesos descontrolados; limpia cache de apt; mueve o borra backups antiguos de forma intencional.

Tarea 7: Inspecciona logs por crecimiento descontrolado y trunca de forma segura

cr0x@server:~$ ls -lh /var/log | tail -n 10
-rw-r----- 1 root adm  12G Dec 25 10:20 syslog
-rw-r----- 1 root adm 1.1G Dec 25 10:20 daemon.log

cr0x@server:~$ sudo truncate -s 0 /var/log/syslog
cr0x@server:~$ sudo systemctl restart rsyslog

Significado: Un syslog gigante puede llenar la raíz. Truncar mantiene el file handle intacto (útil cuando los demonios lo tienen abierto).
Decisión: después de liberar espacio, reinicia pveproxy y sus dependencias; luego arregla la causa del spam en logs.

Tarea 8: Verifica que /etc/pve esté montado y respondiendo (salud de pmxcfs)

cr0x@server:~$ mount | grep -E ' on /etc/pve '
pve:/etc/pve on /etc/pve type fuse.pve (rw,nosuid,nodev,relatime,user_id=0,group_id=0,default_permissions,allow_other)

cr0x@server:~$ timeout 2 ls -la /etc/pve
total 0
drwxr-xr-x 2 root www-data 0 Dec 25 10:25 local
drwxr-xr-x 2 root www-data 0 Dec 25 10:25 nodes
-rw-r----- 1 root www-data 0 Dec 25 10:25 .members

Significado: El montaje FUSE existe y el directorio responde dentro de 2 segundos.
Decisión: si esto se cuelga o agota tiempo, deja de perseguir certificados primero—arregla pve-cluster / el estado de corosync.

Tarea 9: Revisa pve-cluster y corosync/quorum (nodos en clúster)

cr0x@server:~$ systemctl status pve-cluster -l
● pve-cluster.service - The Proxmox VE cluster filesystem
     Loaded: loaded (/lib/systemd/system/pve-cluster.service; enabled)
     Active: active (running) since Mon 2025-12-25 10:05:01 UTC; 28min ago

cr0x@server:~$ pvecm status
Cluster information
-------------------
Name:             prod
Config Version:   17
Transport:        knet
Secure auth:      on

Quorum information
------------------
Date:             Mon Dec 25 10:33:01 2025
Quorum provider:  corosync_votequorum
Nodes:            3
Node ID:          0x00000001
Ring ID:          1.7a
Quorate:          Yes

Significado: El sistema de archivos del clúster está arriba y hay quorum. Bien—tu problema probablemente es local (disco, TLS, conflicto de puerto, paquetes).
Decisión: procede a las comprobaciones de cert/identidad para pveproxy.

Tarea 10: Valida identidad del nodo y resolución de hostname

cr0x@server:~$ hostnamectl --static
pve1

cr0x@server:~$ hostname -f
pve1.example.internal

cr0x@server:~$ getent hosts $(hostname -f)
10.10.10.11     pve1.example.internal pve1

Significado: El hostname resuelve a una IP. Si esto no devuelve nada o la IP es incorrecta, los componentes de Proxmox pueden comportarse de forma extraña.
Decisión: arregla DNS o /etc/hosts primero. No regeneres certificados hasta que la identidad sea correcta.

Tarea 11: Comprueba la sincronización de tiempo y si la hora es plausible

cr0x@server:~$ timedatectl
               Local time: Mon 2025-12-25 10:33:40 UTC
           Universal time: Mon 2025-12-25 10:33:40 UTC
                 RTC time: Mon 2025-12-25 10:33:39
                Time zone: Etc/UTC (UTC, +0000)
System clock synchronized: yes
              NTP service: active
          RTC in local TZ: no

Significado: El tiempo está sincronizado. Si no lo está, los navegadores y TLS te castigarán.
Decisión: si la hora es incorrecta, arregla NTP primero y luego reintenta pveproxy. No persigas caducidad de certificados fantasmas.

Tarea 12: Verifica que el certificado y la clave del proxy de Proxmox existen y son legibles

cr0x@server:~$ ls -l /etc/pve/local/pve-ssl.pem /etc/pve/local/pve-ssl.key
-rw-r----- 1 root www-data 3452 Dec 25 10:25 /etc/pve/local/pve-ssl.pem
-rw-r----- 1 root www-data 1704 Dec 25 10:25 /etc/pve/local/pve-ssl.key

Significado: Los archivos existen. Los permisos muestran root y grupo www-data legibles; eso es típico para componentes web.
Decisión: si faltan, necesitas regenerarlos (después de confirmar que /etc/pve está sano y el hostname es correcto).

Tarea 13: Comprueba fechas de validez y sujeto del certificado (sanity rápida)

cr0x@server:~$ openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -dates -subject
notBefore=Dec 25 10:25:01 2025 GMT
notAfter=Dec 24 10:25:01 2035 GMT
subject=CN = pve1.example.internal

Significado: El certificado es válido en el rango de tiempo y está ligado al CN esperado.
Decisión: si el CN es incorrecto o las fechas son absurdas, arregla hostname/tiempo y regenera certificados.

Tarea 14: Regenera certificados de Proxmox (solo cuando la identidad y /etc/pve estén correctos)

cr0x@server:~$ pvecm updatecerts --force
updating certificate for node pve1
generating SSL certificate... done

cr0x@server:~$ systemctl restart pveproxy
cr0x@server:~$ systemctl status pveproxy -l
● pveproxy.service - PVE API Proxy Server
     Loaded: loaded (/lib/systemd/system/pveproxy.service; enabled)
     Active: active (running) since Mon 2025-12-25 10:35:12 UTC; 2s ago

Significado: La regeneración de certificados funcionó y el proxy ahora se está ejecutando.
Decisión: valida el acceso localmente y luego de forma remota; si falla de forma remota, investiga firewall/LB/reverse proxy.

Tarea 15: Confirma que la UI local responde (evitando DNS y red externa)

cr0x@server:~$ curl -kI https://127.0.0.1:8006/
HTTP/1.1 200 OK
server: pve-api-daemon/3.0
content-type: text/html; charset=utf-8

Significado: Localmente el endpoint funciona. Si los usuarios aún no pueden acceder, es ruta de red, firewall o proxy upstream.
Decisión: revisa firewall del host, firewall perimetral y cualquier configuración de reverse proxy.

Tarea 16: Comprueba si pvedaemon está sano (a menudo comparte la misma causa raíz)

cr0x@server:~$ systemctl status pvedaemon -l
● pvedaemon.service - PVE API Daemon
     Loaded: loaded (/lib/systemd/system/pvedaemon.service; enabled)
     Active: active (running) since Mon 2025-12-25 10:05:03 UTC; 30min ago

Significado: Si pvedaemon también falla, espera un problema más amplio: /etc/pve, disco, paquetes o identidad.
Decisión: trátalo como una falla del plano de gestión, no como un tropiezo de un solo servicio.

Tarea 17: Comprueba por problemas de dpkg/apt tras actualizaciones

cr0x@server:~$ dpkg --audit
The following packages are only half configured, probably due to problems
configuring them the first time. The configuration should be retried using
dpkg --configure <package> or the configure menu option in dselect:
 pve-manager  Proxmox VE virtualization management suite

Significado: La configuración parcial puede romper servicios de formas extrañas.
Decisión: arregla el estado de los paquetes antes de seguir depurando.

Tarea 18: Repara la configuración de paquetes y reinicia limpiamente

cr0x@server:~$ sudo dpkg --configure -a
Setting up pve-manager (8.2.2) ...
Processing triggers for man-db (2.11.2-2) ...

cr0x@server:~$ sudo apt-get -f install
Reading package lists... Done
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

cr0x@server:~$ sudo systemctl restart pveproxy
cr0x@server:~$ systemctl is-active pveproxy
active

Significado: Restauraste un estado consistente de paquetes.
Decisión: si los fallos persisten, vuelve a los logs—ahora los logs son fiables y no artefactos de código a medio instalar.

Tres micro-historias corporativas desde la trinchera

Micro-historia 1: El incidente causado por una suposición equivocada (DNS “no puede ser”)

Una empresa mediana ejecutaba un clúster Proxmox de tres nodos para servicios internos. Una mañana, la UI web en un solo nodo desapareció:
el puerto 8006 daba timeout. El ingeniero on-call asumió que era “algo web” y se centró inmediatamente en reglas del reverse proxy, porque
había habido un cambio reciente en un balanceador interno.

El nodo era accesible por SSH, las VMs estaban en ejecución, pero pveproxy no arrancaba. Los logs mencionaban certificados,
lo que reforzó la narrativa de “web/TLS”. Regeneraron certificados. Sin mejora. Reinstalaron pve-manager.
Todavía muerto. En ese punto fue un outage de dos horas del plano de gestión para ese nodo, con varias “soluciones” abortadas que
complicaron la reversión.

La causa real fue banal: un registro DNS del FQDN del nodo se había actualizado durante un proyecto de renumeración IP, pero un
cluster de resolvers interno seguía sirviendo la dirección antigua. En el nodo Proxmox, getent hosts $(hostname -f) devolvía
una IP inesperada. Algunos componentes estaban convencidos de una identidad; otros veían otra.

Una vez que corrigieron la resolución de nombres de forma consistente (y aseguraron que /etc/hosts coincidiera con la realidad),
regeneraron certificados una vez más y pveproxy arrancó inmediatamente.

La lección no fue “DNS siempre es el problema”. La lección fue que las comprobaciones de identidad pertenecen a los primeros cinco minutos.
Si no verificas tus suposiciones pronto, pasas el resto del incidente tratando síntomas que creaste tú mismo.

Micro-historia 2: La optimización que resultó contraproducente (retención de logs y raíz llena)

Otro entorno estaba “mejorando” la higiene operativa. Alguien decidió aumentar la retención de logs en los nodos Proxmox porque
“nunca tenemos suficiente historial durante incidentes”. Objetivo razonable. La ejecución fue del tipo que hace que los SREs beban agua y miren al vacío.

La retención de logs se incrementó efectivamente desactivando la rotación para algunas facilidades ruidosas y aumentando tamaños de journal. Funcionó
hasta que un pico de latencia de almacenamiento disparó mensajes repetidos de reconnect iSCSI en varios nodos. La tasa de logs pasó de “parloteo”
a “manguera de incendios”, y los volúmenes raíz se llenaron durante la noche.

Cuando / se llenó, pveproxy no pudo arrancar en el reboot porque no podía escribir lo que necesitaba. El equipo persiguió
TLS y problemas de paquetes porque los errores visibles referenciaban operaciones sobre certificados y archivos. No estaban equivocados—esos estaban fallando.
Simplemente no estaban fallando primero.

La solución fue sencilla: liberar espacio y reiniciar servicios. La solución a largo plazo también fue simple, pero requirió disciplina:
políticas de rotación de logs que asuman tasas de peor caso, más monitorización de espacio en disco y uso de inodos, con alertas antes del 95% y antes
de que el journal devore el host.

La optimización salió mal porque cambió un modo de falla: de “nos falta contexto” a “perdimos el plano de gestión”. En ops, los problemas más caros
suelen venir de mejoras bienintencionadas que no se estresaron correctamente.

Micro-historia 3: La práctica aburrida pero correcta que salvó el día (reinicios por orden de dependencias y preservación de evidencia)

Un equipo de servicios financieros ejecutaba nodos Proxmox bajo estricto control de cambios. Sus runbooks no eran llamativos. No eran “innovadores”.
Eran correctos y practicados.

Durante una ventana de mantenimiento de energía, un nodo volvió con pveproxy fallando. El ingeniero on-call no reinició de nuevo.
No reinstaló. No regeneró certificados por costumbre. Siguió el runbook: capturar systemctl status, capturar journalctl,
comprobar disco, comprobar tiempo, comprobar la capacidad de respuesta de /etc/pve y luego verificar conflictos de puerto.

Encontraron que /etc/pve estaba montado pero se colgaba de forma intermitente debido a un estado atascado de pve-cluster tras el evento de energía.
El clúster tenía quorum, pero el proceso de sistema de archivos del clúster local en un nodo estaba triste. Reiniciar servicios en el orden equivocado
habría hecho que el nodo fluctúe entre estados “medio disponibles”.

Reiniciaron pve-cluster de forma limpia, verificaron la capacidad de respuesta de /etc/pve, luego reiniciaron pvedaemon
y después pveproxy. La UI volvió y el incidente terminó con una traza de evidencia completa que facilitó el postmortem.

No pasó nada heroico. Ese fue el punto. La práctica aburrida—arreglar dependencias primero y preservar evidencia—mantuvo el outage corto y evitó que una “solución”
se convirtiera en un incidente secundario.

Errores comunes: síntoma → causa raíz → arreglo

1) “8006 hace timeout” → Asumes firewall → Es que pveproxy no está escuchando

Síntoma: El navegador no puede conectar a https://node:8006.

Causa raíz: pveproxy está caído; el puerto no está vinculado.

Arreglo: Ejecuta ss -ltnp | grep :8006. Si está vacío, lee journalctl -u pveproxy y arregla la falla real de inicio.

2) “pveproxy falla con error de certificado” → Regeneras certificados inmediatamente → El problema real es /etc/pve colgado

Síntoma: Errores sobre /etc/pve/local/pve-ssl.pem ausente o ilegible.

Causa raíz: pmxcfs está poco saludable; /etc/pve no es accesible, así que los archivos “desaparecen”.

Arreglo: Valida mount | grep /etc/pve y timeout 2 ls /etc/pve; arregla pve-cluster primero.

3) “La UI está en blanco” → Culpas a la caché del navegador → La hora del nodo está mal

Síntoma: Advertencias TLS, comportamientos raros de sesión, bucles de login.

Causa raíz: Desfase de reloj; las comprobaciones de validez TLS fallan y las cookies se comportan raro.

Arreglo: timedatectl; restaura NTP; luego reinicia pveproxy si hace falta.

4) “El servicio no arranca después de la actualización” → Reinstalas paquetes al azar → dpkg está medio configurado

Síntoma: Fallos inmediatos al arrancar, módulos faltantes, comportamiento inconsistente tras una actualización.

Causa raíz: Actualización parcial o configuración de dpkg interrumpida.

Arreglo: dpkg --audit, luego dpkg --configure -a y apt-get -f install.

5) “pveproxy dice dirección en uso” → Matas PIDs al azar → Otro servicio está intencionalmente ligado

Síntoma: Fallo de bind en 8006.

Causa raíz: Reverse proxy o servicio de prueba enlazado a 8006.

Arreglo: Identifica con ss -ltnp, cambia ese servicio a otro puerto, y mantén Proxmox en 8006 salvo razón fuerte.

6) “pveproxy falló” → Reboots → El sistema raíz está lleno y el reboot no liberó nada

Síntoma: El servicio falla en cada arranque; los logs se quejan al escribir archivos.

Causa raíz: Disco lleno / inodos llenos.

Arreglo: df -h y df -i, luego elimina/trunca de forma segura y configura umbrales de monitorización.

7) “Funcinó ayer” → Ignoras cambios de hostname → Certificados e identidad de clúster discrepan

Síntoma: CN del certificado no coincide, errores de UI, nombres de nodo inconsistentes.

Causa raíz: Hostname/FQDN cambiado sin actualizar /etc/hosts, DNS y certificados/config del clúster.

Arreglo: Arregla la resolución de nombres primero, luego pvecm updatecerts --force, y después reinicia pveproxy.

Listas de comprobación / plan paso a paso

Checklist A: Triage en los primeros 10 minutos (nodo único o clúster)

1. Haz SSH. Confirma que estás en el nodo correcto: hostname, ip a.
2. Captura evidencia:
   • systemctl status pveproxy -l
   • journalctl -u pveproxy -b --no-pager -n 200
3. Comprueba si está escuchando: ss -ltnp | grep :8006.
4. Comprueba espacio e inodos: df -h, df -i.
5. Comprueba la hora: timedatectl.
6. Comprueba identidad: hostname -f, getent hosts $(hostname -f).
7. Comprueba el sistema de archivos del clúster: mount | grep /etc/pve, timeout 2 ls /etc/pve.
8. Si está en clúster: pvecm status y systemctl status corosync.
9. Sólo después de lo anterior: reinicia dependencias y luego pveproxy.

Checklist B: Orden de reinicio seguro (cuando sospechas problemas de dependencia)

1. Si /etc/pve está colgado: arregla pve-cluster primero.
2. Orden típico de reinicio: pve-cluster → pvedaemon → pveproxy.
3. Verifica cada paso con systemctl is-active y revisa logs inmediatamente si falla.

Checklist C: Reparación de certificados sin autolesionarte

1. Confirma que hostname y FQDN resuelven correctamente (hostname -f, getent hosts).
2. Confirma que la hora es correcta (timedatectl).
3. Confirma que /etc/pve responde (sin cuelgues).
4. Inspecciona archivos de cert/clave y permisos existentes.
5. Regenera: pvecm updatecerts --force.
6. Reinicia pveproxy y verifica con curl -kI https://127.0.0.1:8006/.

Checklist D: Si sospechas actualización parcial

1. Comprueba: dpkg --audit.
2. Repara: dpkg --configure -a.
3. Arregla dependencias: apt-get -f install.
4. Reinstala solo si es necesario (dirigido, no al azar).
5. Reinicia servicios y vuelve a revisar logs.

Preguntas frecuentes

1) ¿Mis VMs están caídas si pveproxy está caído?

Usualmente no. pveproxy es el proxy web/API. Las cargas de trabajo pueden continuar ejecutándose. Verifica con qm list y pct list,
y comprueba la salud de las aplicaciones externamente.

2) ¿Por qué un disco lleno detiene la UI web?

Los servicios necesitan escribir logs, archivos PID, caches y temporales. Cuando / está lleno, los arranques fallan de maneras que parecen no relacionadas.
Revisa df -h y df -i temprano.

3) ¿Puedo cambiar el puerto de la UI de Proxmox desde 8006?

Puedes, pero probablemente no deberías. Cambiar el puerto complica la automatización, la documentación y la respuesta a incidentes. Si debes hacerlo, hazlo de forma intencional
y documenta el cambio. De lo contrario, libera 8006 y deja que Proxmox use su valor por defecto.

4) ¿Cuál es la relación entre pveproxy y pvedaemon?

pvedaemon proporciona la funcionalidad de backend/API; pveproxy la expone por HTTPS. Cuando el plano de gestión está roto
por /etc/pve o problemas de identidad, ambos pueden fallar o comportarse mal.

5) ¿Cuándo debería regenerar certificados?

Cuando los certificados faltan, son inválidos o no coinciden—y solo después de confirmar que la resolución de hostname y el tiempo son correctos, y que
/etc/pve responde. Usa pvecm updatecerts --force.

6) Mi navegador dice que el certificado es inválido. ¿Significa que pveproxy está roto?

No necesariamente. pveproxy puede estar funcionando bien pero presentando un certificado que tu navegador no confía (auto-firmado por defecto) o
un certificado cuyo CN no coincide con el hostname que usaste. Compruébalo con openssl x509 y verifica que conectas con el FQDN esperado.

7) En un clúster, ¿el quorum afecta a pveproxy?

Indirectamente, sí. El quorum y la estabilidad de corosync afectan a pmxcfs y al comportamiento de /etc/pve, y eso afecta a los servicios que leen configuración desde ahí.
Si no tienes quorum, arregla la membresía del clúster antes de hacer reinicios cosméticos de servicios.

8) ¿Qué hago si /etc/pve está lento o se cuelga?

Trata eso como el incidente primario. Revisa pve-cluster y el estado de corosync. Evita editar configuración bajo un /etc/pve colgado;
puede agravar la inconsistencia. Restaura la salud del sistema de archivos del clúster primero.

9) ¿Debería reiniciar el nodo para arreglar pveproxy?

Reiniciar es el último recurso, no la primera respuesta. Puede limpiar un proceso atascado, pero también borra evidencia volátil y no arregla causas raíz como
disco lleno, DNS, paquetes dañados o sincronización de tiempo. Si vas a reiniciar, captura logs primero.

10) pveproxy está en ejecución pero la UI sigue inaccesible desde mi estación. ¿Ahora qué?

Confirma la salud local con curl -kI https://127.0.0.1:8006/. Si local funciona, es problema de ruta de red: reglas de firewall, enrutamiento, VLANs,
reverse proxies upstream o dispositivos corporativos que interceptan TLS.

Conclusión: pasos siguientes para evitar repeticiones

Un pveproxy muerto rara vez es “solo pveproxy”. Es tu plano de gestión diciéndote que algo básico falló: almacenamiento, identidad, tiempo,
sistema de archivos del clúster o integridad de paquetes.

Pasos siguientes que realmente compensan:

• Añadir monitorización de disco raíz y inodos con alertas antes del 90–95% de uso, no al 100% cuando los servicios ya cayeron.
• Estandarizar cambios de identidad de nodo: cambios de hostname/DNS requieren un procedimiento controlado, no un “arreglo rápido” a altas horas.
• Practicar el orden de reparación en una ventana de mantenimiento: recoge logs, valida /etc/pve, luego toca certificados y finalmente reinicia.
• Mantener las actualizaciones aburridas: evita actualizaciones parciales, mantiene el estado de paquetes limpio y no mezcles repos sin plan.
• Documentar cualquier puerto/proxy no por defecto para que el próximo incidente no empiece con una búsqueda del tesoro.

Cuando pveproxy.service failed aparezca de nuevo—y lo hará—ejecuta el guion de diagnóstico rápido, respeta el orden de dependencias y no borres evidencia con reinicios “útiles”.