Proxmox: agente invitado no se está ejecutando — habilitar QEMU Guest Agent y hacerlo permanente

octubre 27, 2025 • febrero 3, 2026 • Lectura: 21 min • Views: 8

¿Te fue útil?

Abres el resumen de la VM en Proxmox para hacer algo rutinario—obtener la IP del invitado, solicitar un apagado limpio, quizá congelar el sistema de archivos antes de una copia de seguridad—y Proxmox responde con el equivalente operativo de un encogimiento de hombros:
«agente invitado no se está ejecutando».

Este es uno de esos errores que parece un «instala un paquete y sigue» hasta que aprendes que también puede significar «hardware virtual equivocado», «servicio enmascarado», «controlador de Windows faltante» o «marcaste la casilla pero olvidaste instalar el agente». Vamos a arreglarlo correctamente, verificarlo y asegurarnos de que permanezca arreglado tras reinicios, actualizaciones y clonados de plantillas.

Qué significa realmente Proxmox con «agente invitado no se está ejecutando»

Proxmox VE se comunica con una VM a través de QEMU. Para hablar hacia el sistema operativo invitado, QEMU utiliza un pequeño servicio auxiliar que se ejecuta dentro del invitado: el QEMU Guest Agent (qemu-guest-agent en Linux, un servicio que se instala mediante las herramientas virtio/guest en Windows).

Cuando Proxmox dice «agente invitado no se está ejecutando», normalmente es uno de estos casos:

El agente no está instalado en el sistema operativo invitado.
El agente está instalado pero el servicio está detenido/deshabilitado (systemd, estado del servicio en Windows, políticas, actualizaciones fallidas).
La VM no tiene el canal de comunicación: el dispositivo virtio-serial y el socket del agente QEMU no están disponibles para el invitado.
Proxmox no está configurado para usarlo: la opción “QEMU Guest Agent” está deshabilitada en la configuración de la VM en Proxmox.
Está ejecutándose, pero no responde: bloqueado por SELinux/AppArmor, un nodo de dispositivo obsoleto o un proceso del agente atascado.

Piénsalo así: la casilla de Proxmox es la línea telefónica, el paquete es el teléfono y el servicio es alguien que realmente contesta. Necesitas los tres.

Hechos y contexto que lo hacen menos misterioso

QEMU Guest Agent existe desde antes de que muchos equipos de nube tuvieran paciencia. Lleva años formando parte del empuje por «hacer las VMs gestionables» en las pilas de virtualización.
Proxmox se basa en el canal QMP de QEMU bajo el capó. Cuando ejecutas acciones del agente (como shutdown), Proxmox usa QMP para invocar comandos del guest-agent.
El transporte del agente suele ser virtio-serial. No es «magia de red», por eso funciona incluso cuando la red del invitado está mal configurada.
Obtener la IP del invitado vía Proxmox a menudo depende del agente. DHCP y trucos con ARP son frágiles; el agente es la fuente autorizada para la información de interfaces del invitado.
El soporte en Windows históricamente quedó detrás de Linux en facilidad de uso. En Linux puedes apt install y listo; en Windows normalmente necesitas drivers virtio e instalador separado del guest-agent.
fsfreeze es una gran razón por la que el agente existe en producción. Hacer snapshots/copies coherentes sin ganchos a nivel de aplicación es difícil; el agente es un compromiso pragmático.
Los clones de plantillas suelen romperlo. La gente crea una «imagen dorada», olvida habilitar el servicio y clona el error cien veces.
El agente no es lo mismo que la consola SPICE o VNC. El acceso a consola es visual; el guest agent es el plano de control operativo. Confundirlos hace perder horas.

Guion de diagnóstico rápido (verifica 1/2/3)

Quieres señales rápido. Aquí está la secuencia que uso cuando una alerta dice «apagado atascado» o «fsfreeze de backup falla» y la interfaz muestra «agente invitado no se está ejecutando».

1) Comprueba si Proxmox habilitó el agente para esta VM

Si Proxmox no está exponiendo el canal virtio-serial, el invitado puede ejecutar el agente todo el día y no servirá de nada.

2) Comprueba el estado del servicio dentro del OS invitado

Instalado no es habilitado. Habilitado no es ejecutándose. Ejecutándose no es necesariamente sano.

3) Comprueba el transporte: dispositivo virtio-serial y socket del agente

Si el invitado no ve /dev/virtio-ports/org.qemu.guest_agent.0 (Linux) o falta el dispositivo en Windows, tienes un problema de hardware virtual/controlador.

Solo después de esos tres pasos me pongo a buscar causas «exóticas» (denegaciones SELinux, perfiles AppArmor, bucles de fallo del agente, incompatibilidades de versión).

Tareas prácticas: comandos, salida esperada y decisiones (12+)

Esta sección es el meollo. Cada tarea incluye: un comando, cómo se ve lo «bueno», cómo se ve lo «malo» y qué decisión tomar a continuación.

Task 1: En el host Proxmox, confirma que la configuración de la VM tiene el agente habilitado

cr0x@server:~$ qm config 101 | egrep -i 'agent|serial|vga|machine'
agent: 1
machine: q35
vga: serial0

Qué significa: agent: 1 es la habilitación por el lado de Proxmox. Si falta o es 0, Proxmox no intentará llamadas al agente.

Decisión: Si agent: 0 o ausente, habilítalo (Task 2). Si está habilitado, pasa a las comprobaciones dentro del invitado (Task 5+).

Task 2: Habilita la opción QEMU Guest Agent en Proxmox (CLI, reproducible)

cr0x@server:~$ qm set 101 --agent enabled=1,fstrim_cloned_disks=1
update VM 101: -agent enabled=1,fstrim_cloned_disks=1

Qué significa: Esto cambia la misma opción que la casilla de la UI. El opcional fstrim_cloned_disks=1 es una mejora para discos thin-provisioned (especialmente tras clonar).

Decisión: Tras habilitar, reinicia la VM si hace falta para asegurar que el puerto virtio-serial esté presente (Task 4). Luego verifica la capacidad de respuesta del agente (Task 3).

Task 3: Pide a Proxmox que haga ping al agente invitado vía QMP

cr0x@server:~$ qm agent 101 ping
{"return":{}}

Qué significa: Si obtienes un retorno JSON, QEMU puede hablar con el agente. Si obtienes un error tipo «QEMU guest agent is not running», Proxmox no puede alcanzarlo.

Decisión: Si el ping funciona, el error en la interfaz está obsoleto o el problema es específico de otro comando (como fsfreeze). Si el ping falla, revisa el servicio y el dispositivo en el invitado (Tasks 5–8).

Task 4: Confirma que el puerto virtio-serial está presente en el hardware de la VM (lado host)

cr0x@server:~$ qm monitor 101 --cmd 'info chardev'
chardev: org.qemu.guest_agent.0
  backend: socket
  path: /var/run/qemu-server/101.qga

Qué significa: Esto muestra que QEMU creó un socket para el agente. Si org.qemu.guest_agent.0 no aparece, el canal del guest agent no está configurado/disponible.

Decisión: Si falta, vuelve a comprobar agent: 1 y asegúrate de haber reiniciado la VM tras los cambios. Si está presente, céntrate dentro del invitado.

Task 5: Dentro de un invitado Linux, confirma que el paquete esté instalado

cr0x@server:~$ dpkg -l | grep -E '^ii\s+qemu-guest-agent\b'
ii  qemu-guest-agent  1:8.2+dfsg-1+deb12u1  amd64  Guest-side QEMU helper daemon

Qué significa: Si ves la línea ii, está instalado. Si no ves nada, no está instalado.

Decisión: Si no está instalado, instálalo (Task 6). Si está instalado, comprueba el estado del servicio (Task 7).

Task 6: Instala el agente en invitados Debian/Ubuntu

cr0x@server:~$ sudo apt-get update
Hit:1 http://deb.debian.org/debian bookworm InRelease
Reading package lists... Done

cr0x@server:~$ sudo apt-get install -y qemu-guest-agent
Reading package lists... Done
Building dependency tree... Done
The following NEW packages will be installed:
  qemu-guest-agent
Setting up qemu-guest-agent (1:8.2+dfsg-1+deb12u1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/qemu-guest-agent.service → /lib/systemd/system/qemu-guest-agent.service.

Qué significa: En distros con systemd, la instalación suele habilitar el servicio. No confíes ciegamente; verifica.

Decisión: Pasa a la Task 7 para confirmar que se está ejecutando y está sano.

Task 7: Comprueba el estado del servicio del agente en Linux (systemd)

cr0x@server:~$ systemctl status qemu-guest-agent --no-pager
● qemu-guest-agent.service - QEMU Guest Agent
     Loaded: loaded (/lib/systemd/system/qemu-guest-agent.service; enabled; preset: enabled)
     Active: active (running) since Thu 2025-12-26 11:14:02 UTC; 2min 10s ago
   Main PID: 623 (qemu-ga)
      Tasks: 1 (limit: 18936)
     Memory: 4.1M
        CPU: 82ms

Qué significa: Deseas ver enabled y active (running). Si está «disabled», regresará tras reinicio. Si está «failed», necesitas logs (Task 8).

Decisión: Si no está habilitado, habilítalo (Task 9). Si falló, revisa los logs y los nodos de dispositivo.

Task 8: Lee los logs del agente para ver si puede abrir el puerto virtio

cr0x@server:~$ journalctl -u qemu-guest-agent -b --no-pager | tail -n 30
Dec 26 11:13:58 vm101 qemu-ga[603]: info: guest agent started
Dec 26 11:13:58 vm101 qemu-ga[603]: error: failed to open /dev/virtio-ports/org.qemu.guest_agent.0: No such file or directory
Dec 26 11:13:58 vm101 systemd[1]: qemu-guest-agent.service: Main process exited, code=exited, status=1/FAILURE
Dec 26 11:13:58 vm101 systemd[1]: qemu-guest-agent.service: Failed with result 'exit-code'.

Qué significa: El agente está instalado, systemd intenta arrancarlo, pero el puerto virtio no está presente dentro del invitado. Eso casi siempre es un problema de configuración de hardware de la VM en Proxmox o de falta del driver virtio (Windows) / módulo de kernel (raro en Linux).

Decisión: Vuelve al host: confirma agent: 1, confirma que QEMU creó el socket (Task 4), reinicia la VM. Si sigue faltando, inspecciona los dispositivos del invitado (Task 10).

Task 9: Habilita y arranca el servicio del agente (y desenmascara si hace falta)

cr0x@server:~$ sudo systemctl unmask qemu-guest-agent
Removed "/etc/systemd/system/qemu-guest-agent.service".

cr0x@server:~$ sudo systemctl enable --now qemu-guest-agent
Created symlink /etc/systemd/system/multi-user.target.wants/qemu-guest-agent.service → /lib/systemd/system/qemu-guest-agent.service.

Qué significa: unmask soluciona la situación de «alguien lo deshabilitó intencionalmente». enable --now lo hace persistente y lo arranca inmediatamente.

Decisión: Vuelve a ejecutar Task 3 desde el host. Si el ping funciona, el problema básico está resuelto.

Task 10: Verifica que exista el dispositivo virtio-ports dentro del invitado Linux

cr0x@server:~$ ls -l /dev/virtio-ports/
total 0
crw------- 1 root root 241, 0 Dec 26 11:14 org.qemu.guest_agent.0

Qué significa: Este es el nodo de dispositivo que el agente necesita. Si el directorio existe pero el archivo no, el invitado no ve el endpoint virtio-serial.

Decisión: Si falta: confirma que el agente de la VM está habilitado y reinicia el invitado; revisa cambios en el tipo de máquina; verifica si migraste desde otro hipervisor con dispositivos inusuales. Si está presente: el agente debería poder arrancar; revisa AppArmor/SELinux si aún no puede abrirlo (Task 11).

Task 11: Busca interferencias de SELinux o AppArmor (raro, pero real)

cr0x@server:~$ sudo aa-status --enabled
apparmor module is loaded.
apparmor filesystem is mounted.
35 profiles are loaded.
0 profiles are in complain mode.
0 profiles are in enforce mode.

Qué significa: Si ves un perfil que aplica restricciones sobre qemu-ga, puede impedir el acceso a dispositivos. Las denegaciones de SELinux pueden producir el mismo efecto.

Decisión: Si hay enforcement y los logs muestran denegaciones, ajusta la política o configura correctamente el perfil del agente. No «desactives la seguridad» como primera reacción.

Task 12: Desde Proxmox, obtén las interfaces de red del invitado y confirma que el agente está entregando datos

cr0x@server:~$ qm agent 101 network-get-interfaces
{"return":[{"name":"lo","ip-addresses":[{"ip-address":"127.0.0.1","ip-address-type":"ipv4","prefix":8}],"statistics":{"rx-bytes":1200,"tx-bytes":1200}},{"name":"ens18","ip-addresses":[{"ip-address":"10.10.20.41","ip-address-type":"ipv4","prefix":24},{"ip-address":"fe80::f816:3eff:fe1b:9d2a","ip-address-type":"ipv6","prefix":64}],"statistics":{"rx-bytes":12093284,"tx-bytes":2209381}}]}

Qué significa: Este es el pago: información autoritativa de interfaces e IP sin trucos fragiles con ARP.

Decisión: Si esto funciona, «agente invitado no se está ejecutando» está resuelto. Si el ping funciona pero esto falla, tu agente está vivo pero limitado—a menudo por una incompatibilidad de versión o permisos restringidos.

Task 13: Verifica apagado limpio a través del agente (para no forzar cortes de energía)

cr0x@server:~$ qm shutdown 101 --timeout 60
VM 101 shutting down

Qué significa: Con un agente funcional, Proxmox puede solicitar un apagado in-guest. Sin él, Proxmox puede recurrir a ACPI, que es menos fiable según el OS y la configuración.

Decisión: Si la VM no se apaga, revisa el manejo de energía del OS invitado y los logs del agente. Si se apaga, deja de usar «Stop» como tu botón de apagado por defecto.

Task 14: Prueba los hooks de fsfreeze si dependes de backups consistentes

cr0x@server:~$ qm agent 101 fsfreeze-status
{"return":"thawed"}

cr0x@server:~$ qm agent 101 fsfreeze-freeze
{"return":0}

cr0x@server:~$ qm agent 101 fsfreeze-status
{"return":"frozen"}

cr0x@server:~$ qm agent 101 fsfreeze-thaw
{"return":0}

Qué significa: Si freeze/thaw funciona, puedes usar coherencia asistida por el agente en backups. Si falla con «command not supported», el agente puede ser demasiado antiguo o compilado sin soporte.

Decisión: Si necesitas snapshots coherentes, actualiza el paquete del guest agent y confirma que el sistema de archivos del invitado soporta freeze (algunas configuraciones no funcionan bien).

Task 15: En invitados Windows, confirma que el servicio existe y se está ejecutando

Windows no trae QEMU Guest Agent por defecto. Normalmente lo instalas como parte del paquete de herramientas de virtio guest.

cr0x@server:~$ qm agent 202 ping
qemu agent is not running

Esa salida por sí sola no dice qué está mal; solo indica que Proxmox no lo alcanza. En la VM Windows, validarías el servicio QEMU GA y la presencia del driver virtio-serial (Device Manager) y luego reintentarías qm agent.

Task 16: Comprobación de sanidad en el host: ¿se está creando el socket qga?

cr0x@server:~$ ls -l /var/run/qemu-server/101.qga
srw-rw---- 1 root root 0 Dec 26 11:14 /var/run/qemu-server/101.qga

Qué significa: Este es el socket UNIX que QEMU usa para el canal del guest agent. Si no existe, QEMU no está configurado para proveer el canal (o la VM no está en ejecución).

Decisión: Si falta: revisa el estado de la VM (qm status 101), vuelve a comprobar agent: 1, y busca errores de inicio en journalctl para pvedaemon/pveproxy si sospechas problemas de manejo de configuración.

Haz que quede: configuración persistente que sobrevive plantillas y actualizaciones

Arreglar la VM de hoy es fácil. Arreglar las clonaciones del mes que viene es donde los sistemas de producción mueren en silencio.

1) Incorpora el agente en tus plantillas, no en tus runbooks

Si creas plantillas (y deberías), trata QEMU Guest Agent como tratas SSH: instalado, habilitado, validado. Para plantillas Linux:

Instala qemu-guest-agent
Habilítalo (systemctl enable --now qemu-guest-agent)
Verifica que el nodo de dispositivo exista después del primer arranque bajo Proxmox

La cláusula «primer arranque bajo Proxmox» importa si la plantilla se creó en otro hipervisor. El puerto virtio-serial es hardware virtual. Si construyes en un hipervisor y ejecutas en otro, puedes «habilitar un servicio con éxito» que no tiene con quién hablar.

2) No trates la casilla de Proxmox como metadata opcional

En Proxmox, habilitar el agente en la VM no es cosmético. Afecta la configuración de dispositivos de QEMU y qué comandos Proxmox siquiera intentará. Haz que se aplique:

Configúrala en las plantillas antes de convertir a template
Actívala automáticamente durante el aprovisionamiento (CLI/API)
Audita las VMs existentes y remedia

3) Haz la habilitación del servicio idempotente

Las correcciones manuales puntuales no escalan. Usa gestión de configuración (Ansible, Salt, lo que uses) para imponer:

Paquete instalado
Servicio habilitado y en ejecución
Opcional: una comprobación de salud que valide que existe el puerto virtio

No necesitas orquestación sofisticada. Necesitas consistencia aburrida.

4) Vigila regresiones tras actualizaciones de SO y «hardening»

Las dos fuentes más comunes de regresiones:

Scripts de imagen dorada que endurecen y deshabilitan «servicios desconocidos». Enhorabuena, acabas de desactivar tu integración con el hipervisor.
Actualizaciones del SO que cambian presets de systemd o reemplazan paquetes; el servicio queda en disabled, o el binario del agente cambia su comportamiento.

Broma #1: A los equipos de seguridad les encanta «deshabilitar todo lo que no reconocen» hasta que el hipervisor no puede apagar la VM y la «mesa de incidentes» se convierte en terapia de grupo.

5) Sabe para qué sirve el agente—y para qué no

El guest agent ayuda con:

Apagado/reinicio limpio
Reporte de IP del invitado
Congelar/descongelar sistemas de ficheros
Ganchos de sincronización de tiempo en algunas configuraciones

No es:

Un reemplazo del monitoring
Un shell remoto
Una solución mágica para redes internas rotas

Tres micro-historias corporativas (cómo los equipos rompen esto en la vida real)

Micro-historia 1: El incidente causado por una suposición equivocada

Una empresa mediana migró desde una plataforma de virtualización antigua a Proxmox. Tenían una lista de verificación: importar discos de VM, arrancar, validar la app. Las aplicaciones arrancaron. Todos declararon victoria. Luego llegó la primera ventana de mantenimiento.

El ingeniero de operaciones intentó apagar un lote de VMs limpiamente para parchear hosts. Proxmox mostró «agente invitado no se está ejecutando» en un subconjunto no trivial. Encogieron los hombros y usaron «Stop» porque la ventana avanzaba. Eso no es un apagado; es cortar la corriente.

Algunas bases de datos volvieron «bien» tras encender. Una no. Arrancó, pero el tiempo de replay de la base de datos fue doloroso y la capa de aplicación empezó a hacer timeouts. El postmortem olía a retrospectiva: «Asumimos que ACPI funcionaría en todas partes. Asumimos que las VMs importadas tenían las mismas herramientas del invitado. Asumimos que ‘Stop’ es seguro.»

La solución fue poco glamorosa: habilitar el agente en cada VM, instalarlo dentro de los invitados y automatizar la remediación. Además, enseñar a la gente que «Stop» es el hacha de emergencia—a veces necesaria, nunca por defecto.

Micro-historia 2: La optimización que salió mal

Otra organización persiguió mejoras en el tiempo de arranque y «imágenes minimalistas». Recortaron servicios y paquetes de las plantillas, incluyendo cosas que sonaban opcionales. QEMU Guest Agent parecía opcional. Lo quitaron.

Las plantillas arrancaban más rápido. El tablero lucía limpio. Las primeras semanas fueron tranquilas. Luego los backups empezaron a lanzar errores intermitentes: comandos de congelado fallaban en algunas VMs. El sistema de backup cayó en snapshots crash-consistent. Nadie lo notó porque no se probaban restores frecuentemente (clásico).

Meses después se necesitó un restore por una implantación corrupta. La VM restaurada arrancó, pero los datos quedaron incoherentes de la forma típica de los backups crash-consistent. La «optimización» ahorró segundos por arranque y costó un día de recuperación y muchas preguntas incómodas.

Reintrodujeron el agente, validaron fsfreeze en las cargas que lo requerían y documentaron excepciones. La lección no fue «nunca optimizar». Fue «no optimices fuera del control operativo».

Micro-historia 3: La práctica aburrida pero correcta que salvó el día

Un equipo de servicios financieros operaba clusters Proxmox con control de cambios estricto. Su práctica era aburrida: auditorías semanales de configuración de VMs, habilitación forzada del agente y un script pre-mantenimiento que comprobaba salud del agente antes de parchear hosts.

Durante un ciclo rutinario de reinicio de hosts, una VM se negó obstinadamente a apagarse limpiamente. El script la marcó: ping del agente falló, pero la VM estaba por lo demás sana. El on-call tuvo tiempo para investigar sin retrasar toda la ventana.

El culpable fue una actualización del OS invitado que enmascaró el servicio qemu-guest-agent por un conflicto de política local. Como lo detectaron antes de la ola de apagados, lo arreglaron en el invitado, confirmaron el ping y la VM se apagó limpiamente.

No pasó nada dramático. Nadie fue alabado en un all-hands. Ese es el punto. Los controles aburridos evitan incidentes emocionantes.

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

Estos son los que sigo viendo en campo. Los síntomas se parecen; las causas raíz no.

1) Síntoma: La UI de Proxmox muestra «agente invitado no se está ejecutando» después de instalar el paquete

Causa raíz: La configuración de VM de Proxmox agent: 1 no está habilitada, por lo que no existe el canal virtio-serial.
Solución: qm set <vmid> --agent enabled=1, reinicia la VM, luego qm agent <vmid> ping.

2) Síntoma: `systemctl status qemu-guest-agent` muestra «failed to open /dev/virtio-ports/…»

Causa raíz: El invitado no ve el dispositivo virtio-serial. Usualmente el agente está deshabilitado por el lado de Proxmox, o el invitado arrancó sin ese hardware virtual.
Solución: Habilita el agente en Proxmox, reinicia. Confirma /dev/virtio-ports/org.qemu.guest_agent.0 existe.

3) Síntoma: El ping al agente funciona, pero falta la dirección IP en el resumen de Proxmox

Causa raíz: El agente corre pero no reporta información de red (agente antiguo, permisos restringidos, Network Manager conflictivo, nombres de interfaz/containers).
Solución: Usa qm agent network-get-interfaces para ver lo reportado; actualiza el guest agent; asegúrate de que el invitado tenga configuración de interfaz estable.

4) Síntoma: El apagado se queda colgado, Proxmox caduca y luego pulsas «Stop»

Causa raíz: El agente no funciona y ACPI no es manejado correctamente por el OS invitado; o el OS está degradado.
Solución: Arregla el agente primero. Si el agente está sano, revisa logs y servicios de apagado del invitado. Usa «Stop» solo aceptando la posibilidad de inconsistencias en el sistema de archivos.

5) Síntoma: Los backups se quejan de fsfreeze o pasan inesperadamente a crash-consistent

Causa raíz: El agente no corre, o fsfreeze no está soportado/funcionando en el invitado (sistema de ficheros no soportado, agente demasiado antiguo, una aplicación mantiene locks).
Solución: Valida con qm agent fsfreeze-status y congela/descongela manualmente. Actualiza el agente. Excluye cargas donde fsfreeze sea arriesgado y usa hooks a nivel de aplicación.

6) Síntoma: Funciona en un nodo, falla tras migración en vivo a otro

Causa raíz: Normalmente no es «específico del nodo», pero podrías ver problemas de sincronización o versiones distintas de QEMU. A veces el proceso del agente en el invitado está atascado y solo se recupera con reinicio, no con migración.
Solución: Confirma ping del agente antes y después de la migración. Si falla consistentemente en un nodo, revisa paquetes QEMU del nodo y los logs del host.

7) Síntoma: Tras el «hardening», el servicio está «masked»

Causa raíz: Un script de baseline enmascaró la unidad para prevenir arranque.
Solución: systemctl unmask qemu-guest-agent, luego enable --now. Arregla el baseline para que deje de hacerlo.

Listas de verificación / plan paso a paso

Checklist A: Arregla una sola VM (invitado Linux) en menos de 10 minutos

En el host Proxmox: qm config <vmid> | grep -i agent → si no está habilitado, ejecuta qm set <vmid> --agent enabled=1.
Reinicia la VM (sí, de verdad) si acabas de habilitar el canal del agente.
En el invitado: instala qemu-guest-agent con tu gestor de paquetes.
En el invitado: systemctl enable --now qemu-guest-agent.
En el invitado: verifica con ls -l /dev/virtio-ports/ que aparece org.qemu.guest_agent.0.
En el host: qm agent <vmid> ping y qm agent <vmid> network-get-interfaces.

Checklist B: Haz que se mantenga en plantillas y clones

Actualiza tus plantillas base para incluir qemu-guest-agent instalado y habilitado.
Asegúrate de que la configuración de VM de la plantilla tenga agent: 1.
Automatiza una comprobación post-provisión: desde el host qm agent <vmid> ping.
Audita las VMs semanalmente: marca las que no tienen agent: 1 o donde falle el ping.
Enseña a tu equipo de ops que «Stop» no es apagado; es un corte forzado.

Checklist C: Cuando los backups dependen de coordinación con el invitado

Para cada clase de workload, decide explícitamente: ¿es aceptable crash-consistent o necesitas fsfreeze/lógicas aware de la app?
Prueba fsfreeze-freeze y fsfreeze-thaw en una ventana de baja carga.
Monitorea timeouts de freeze; no permitas que un «intent de freeze» cuelgue los backups indefinidamente.

Preguntas frecuentes

1) ¿La casilla «QEMU Guest Agent» de Proxmox es suficiente?

No. Habilita el canal en la VM. Aún necesitas que el agente esté instalado y en ejecución dentro del sistema operativo invitado.

2) ¿Necesito reiniciar después de habilitar el agente en Proxmox?

A menudo, sí. Añadir el endpoint virtio-serial es un cambio de hardware virtual; los invitados normalmente lo detectan correctamente al reiniciar.

3) ¿Por qué me importa el agente si mi VM funciona bien?

Porque «funciona bien» es lo que dices antes de necesitar apagar limpiamente 40 VMs durante una emergencia de host, o antes de necesitar backups coherentes.

4) ¿El agente afecta al rendimiento?

De forma negligible. Es un demonio pequeño esperando peticiones. Si consume CPU real, algo más va mal (por ejemplo, bucles de fallo).

5) ¿Puedo obtener direcciones IP de invitados sin el agente?

A veces, mediante tablas ARP o leases DHCP. Es poco fiable en VLANs, firewalls y entornos multi-NIC. El agente es el método confiable.

6) Mi agente está ejecutándose, pero Proxmox aún muestra «no se está ejecutando». ¿Qué pasa?

Normalmente el invitado no puede ver el dispositivo virtio-serial, o Proxmox no habilitó el canal del agente. Confirma agent: 1, confirma que el socket existe y revisa /dev/virtio-ports/… en el invitado.

7) ¿Es seguro QEMU Guest Agent desde la perspectiva de seguridad?

Amplía lo que el host puede solicitar al invitado. Ese es su propósito. Si no confías en tus administradores del hipervisor, tienes problemas mayores que este paquete.

8) ¿Puedo usarlo en invitados Windows?

Sí, pero no es «apt install». Necesitas instalar el guest agent de Windows y disponer del driver virtio-serial. Valida el servicio de Windows y las entradas del Device Manager.

9) ¿Debo habilitar fsfreeze para todas las VMs?

No. Úsalo donde aporte valor (bases de datos, apps stateful) y donde lo hayas probado. Para algunas cargas, snapshots crash-consistent son aceptables y más simples.

10) ¿Cuál es la verificación de salud más fiable?

qm agent <vmid> ping desde el host, más un comando objetivo como network-get-interfaces. El ping demuestra conectividad, no utilidad.

Conclusión: siguientes pasos que puedes hacer hoy

Arreglar «agente invitado no se está ejecutando» no es ingeniería heroica. Es higiene básica que evita dolores evitables: apagados feos, falta de visibilidad de IPs y backups inconsistentes. Haz lo aburrido. Tu yo futuro estará menos ocupado.

Pasos prácticos:

Elige una VM afectada y ejecuta el triage desde el host: qm config → qm agent ping → comprueba el socket qga.
En el invitado, instala y habilita el agente; verifica que exista el puerto virtio.
Actualiza tus plantillas y aprovisionamiento para que las nuevas VMs no repitan el problema.
Añade una auditoría semanal: las VMs con agent: 0 o fallos de ping se corrigen antes de las ventanas de mantenimiento.

Cita (idea parafraseada) de Gene Kranz: «Failure isn’t an option» es menos un eslogan y más una partida del presupuesto operativo—pagada en verificaciones, pruebas y disciplina.

Broma #2: Si tu único procedimiento de apagado es «Stop», no tienes un procedimiento—tienes un lanzamiento de moneda con mejor UI.