Capítulo 14: Troubleshooting y Debugging

Diagnóstico rápido

Antes de cualquier troubleshooting, recopila información del entorno:

# Estado de KVM
[ -r /dev/kvm ] && [ -w /dev/kvm ] && echo "KVM: OK" || echo "KVM: FALLA"

# Versión de Firecracker
firecracker --version

# Kernel del host
uname -r

# Módulos KVM cargados
lsmod | grep kvm

# Logs del kernel (problemas de KVM aparecen aquí)
sudo dmesg | grep -i "kvm\|vmx\|svm" | tail -20

Errores comunes y soluciones

Error: /dev/kvm no existe o sin permisos

Error: Failed to open /dev/kvm: Permission denied

Causa: El usuario no tiene acceso a /dev/kvm.

# Solución 1: Agregar al grupo kvm (requiere logout/login)
sudo usermod -aG kvm ${USER}

# Solución 2: ACL temporal
sudo setfacl -m u:${USER}:rw /dev/kvm

# Solución 3: Verificar que el módulo está cargado
sudo modprobe kvm_intel || sudo modprobe kvm_amd

Error: el socket de la API no responde

curl: (7) Failed to connect to localhost port 80

Causa: Firecracker no está corriendo o el socket tiene ruta incorrecta.

# Verificar que el proceso está vivo
pgrep -a firecracker

# Verificar que el socket existe
ls -la /tmp/firecracker.socket

# Intentar con el path explícito
curl --unix-socket /tmp/firecracker.socket http://localhost/version

Error: la VM no arranca (no hay salida en consola)

# Verificar que el kernel existe y es legible
ls -lh ./vmlinux
file ./vmlinux
# Debe ser: ELF 64-bit LSB executable, x86-64

# Verificar que el rootfs existe y es ext4
file ./rootfs.ext4
# Debe ser: Linux rev 1.0 ext4 filesystem data

# Arrancar con logs activados para ver errores
firecracker --api-sock /tmp/fc.sock &
curl -s -X PUT --unix-socket /tmp/fc.sock \
  --data '{"log_path": "/tmp/fc.log", "level": "Debug"}' \
  "http://localhost/logger"
# ... configurar boot-source, drives, machine-config ...
curl -s -X PUT --unix-socket /tmp/fc.sock \
  --data '{"action_type": "InstanceStart"}' \
  "http://localhost/actions"

cat /tmp/fc.log

Error: kernel panic durante el boot

Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(0,0)

Causa: El rootfs no está configurado correctamente o el kernel no tiene soporte para VirtIO-Block.

# Verificar configuración del drive
curl -s --unix-socket /tmp/fc.sock "http://localhost/drives/rootfs" | jq .

# Verificar que el path del rootfs es absoluto o correcto
# Firecracker resuelve paths relativos desde el directorio donde se lanzó
pwd  # ← Firecracker busca archivos aquí

# Solución: usar paths absolutos en la configuración

Error: la red no funciona desde el guest

# Verificar que el TAP device existe en el host
ip link show tap0

# Verificar que ip_forward está habilitado
cat /proc/sys/net/ipv4/ip_forward
# Debe ser: 1

# Verificar reglas iptables
sudo iptables -t nat -L POSTROUTING -n -v
sudo iptables -L FORWARD -n -v

# Desde el guest, verificar interfaz
ip addr show eth0
ip route show
# Si no hay ruta default, agregar:
# ip route add default via <IP_HOST>

Error al restaurar snapshot

Error: Failed to restore snapshot: Invalid magic number

Causa: La versión de Firecracker que creó el snapshot es diferente a la que intenta restaurarlo.

# Los snapshots NO son portables entre versiones de Firecracker
firecracker --version  # Debe coincidir con la versión que creó el snapshot

# Verificar integridad del archivo de snapshot
file ./snapshots/vm1/snapshot

# El archivo de memoria debe tener el tamaño correcto
ls -lh ./snapshots/vm1/memory
# Debe ser ≈ mem_size_mib de la VM original

Error: alta latencia con cgroups v1

Síntoma: Tiempo de arranque mucho mayor al esperado (> 500 ms).

# Verificar versión de cgroups activa
stat -f /sys/fs/cgroup | grep Type
# cgroupv2 es superior para Firecracker

# Con jailer, especificar versión correcta
jailer --cgroup-version 2 ...

# Para migrar a cgroups v2 en el host (si usas cgroupv1)
# Agregar a /etc/default/grub:
# GRUB_CMDLINE_LINUX="systemd.unified_cgroup_hierarchy=1"
sudo update-grub && sudo reboot

Herramientas de debugging

Logs detallados de Firecracker

# Habilitar logs antes de arrancar la VM
curl -s -X PUT --unix-socket /tmp/fc.sock \
  --data '{
    "log_path": "/tmp/fc-debug.log",
    "level": "Debug",
    "show_level": true,
    "show_log_origin": true
  }' \
  "http://localhost/logger"

# Seguir los logs en tiempo real
tail -f /tmp/fc-debug.log

Depurar el guest con GDB

# Arrancar Firecracker con soporte de debugging
firecracker --api-sock /tmp/fc.sock \
  --no-seccomp \
  -- --gdb-socket /tmp/fc-gdb.sock

# En otra terminal, conectar GDB
gdb ./vmlinux
(gdb) target remote /tmp/fc-gdb.sock
(gdb) continue

Ver gdb-debugging.md para más detalles.

Capturar tráfico de la API

# Interceptar todas las llamadas a la API con socat
socat -v UNIX-LISTEN:/tmp/fc-proxy.sock,fork \
  UNIX-CONNECT:/tmp/firecracker.sock 2>&1 | tee /tmp/api-traffic.log

Limitaciones conocidas

Limitación	Descripción	Workaround
Sin migración en vivo	Los snapshots requieren pausar la VM	Usar Diff snapshots frecuentes
Red no garantizada post-resume	La conectividad puede romperse al resumir	Re-configurar red en el guest
Snapshots no portables entre versiones	Cada versión de FC tiene formato propio	Fijar versión de FC en producción
Max 32 vCPUs	Límite de arquitectura del modelo de máquina	Usar múltiples VMs para cargas grandes
Sin GPU passthrough	VirtIO-GPU no implementado	Usar hardware passtrought con VFIO
Solo x86_64 y aarch64	No hay emulación cruzada	Usar la arquitectura nativa

Lista de verificación de problemas

□ /dev/kvm existe y el usuario tiene permisos de lectura/escritura
□ El módulo kvm_intel o kvm_amd está cargado
□ El kernel vmlinux es formato ELF sin comprimir (no .gz)
□ El rootfs tiene soporte para VirtIO-Block en el kernel
□ Los paths a kernel y rootfs son accesibles desde el CWD de Firecracker
□ El TAP device está up y con la IP configurada (para red)
□ ip_forward está habilitado (para NAT)
□ Los logs de Firecracker están habilitados para obtener errores detallados
□ La versión de Firecracker coincide si estás restaurando snapshots

Referencia

• gdb-debugging.md
• Reportar bugs en Firecracker
• FAQ oficial
• Changelog por versión