Procedimiento de Diagnóstico Offline de VM mediante Guestmount y Logs

Fecha:

23 de julio de 2026

Autor:

Raúl Vílchez

Categoría:

Administración de Sistemas / Virtualización (libvirt / guestfs)

Estado:

Aprobado

Introducción

Durante el despliegue no interactivo de imágenes base (Golden Images) con enrolamiento automático en FreeIPA / IdM, pueden presentarse fallos en la fase de primer arranque (first boot).

Si el acceso interactivo por TTY o SSH no está disponible (por ejemplo, por no disponer de contraseñas locales activas o llaves inyectadas), es necesario inspeccionar los registros del sistema de forma offline utilizando herramientas de manipulación de discos sin necesidad de arrancar el dominio virtualizado.

Requisitos Previos

  • Permisos de superusuario (root o reglas de sudo configuradas).

  • Paquete libguestfs-tools o la utilidad guestmount instalada en el hipervisor.

  • La máquina virtual objetivo debe estar completamente apagada.

Warning

Riesgo de Corrupción de Datos: Nunca intente montar el disco de una máquina virtual activa con guestmount en modo lectura/escritura (--rw). Siempre asegúrese de detener la máquina antes o de utilizar el modo de solo lectura (--ro).

Procedimiento de Diagnóstico

1. Apagado Forzado o Controlado del Nodo

Asegurar el estado inactivo del dominio virtual mediante virsh:

virsh destroy buildlab

2. Creación del Punto de Montaje Operativo

Crear un directorio temporal en el hipervisor para albergar el sistema de archivos guest:

mkdir -p /mnt/mnt_buildlab

3. Montaje del Disco en Modo Solo Lectura

Inspeccionar el disco inyectando el controlador FUSE en modo seguro (--ro):

guestmount -d buildlab -i --ro /mnt/mnt_buildlab

Note

El parámetro -i (inspect) detecta automáticamente las particiones, el volumen LVM y la raíz (/) del sistema operativo huésped.

4. Inspección del Log de Enrolamiento

Consultar el archivo de log inyectado para determinar el motivo exacto de la falla en el script idm-join.sh:

cat /mnt/mnt_buildlab/var/log/idm-setup.log

Resolución de Incidencias Comunes

Si el log muestra el error:

Joining realm failed: SASL Bind failed
    Invalid credentials

El motivo suele responder a un token OTP caducado o a la presencia de caracteres de control invisibles (saltos de línea \r\n) introducidos al copiar y pegar las credenciales.

5. Desmontaje Limpio del Sistema de Ficheros

Una vez completada la revisión o corrección offline, desmontar la estructura FUSE:

guestunmount /mnt/mnt_buildlab

Verificación del Estado

Una vez desmontado el volumen, se puede reanudar la ejecución normal del dominio para reintentar el flujo de enrolamiento:

virsh start buildlab