¿El módulo WireGuard no se carga tras actualizar el kernel? Revise esto

Su túnel funcionaba ayer, la máquina se reinició tras una actualización y ahora la interfaz no levanta. En un sistema donde WireGuard se compila como módulo externo, la causa habitual es que el módulo del disco pertenece a una versión del kernel distinta de la que se ejecuta ahora. Las cabeceras con un nombre similar en la misma máquina no demuestran nada sobre esa coincidencia. Solo la cadena de versión lo decide.

Kernel en ejecución o kernel instalado

Una actualización instala un paquete de kernel nuevo y deja el viejo en el disco hasta que la máquina se reinicia. Tras el reinicio cambia la versión en ejecución, y cualquier módulo compilado contra la anterior queda inservible aunque sus archivos sigan ahí. Esa brecha explica el informe habitual de una máquina que estaba bien antes de un reinicio y rota después, sin ningún cambio de configuración entre medias. También explica por qué reinstalar las cabeceras a veces parece resolver el problema y a veces no.

El paquete de cabeceras que instala puede corresponder al paquete de kernel más reciente en lugar del kernel que realmente arrancó, y nada en el nombre del paquete distingue esos casos; solo lo hace la cadena de versión. Compruebe qué se ejecuta antes de comprobar qué está instalado.

Tres comprobaciones antes de reconstruir

La primera comprobación es qué kernel se ejecuta. La segunda es si existe un módulo para esa versión y si se puede encontrar. La tercera es si el kernel ya lo ha cargado. La cuarta pregunta, si se puede crear la interfaz, pone a prueba los privilegios y no el módulo, así que va después de la reconstrucción y no en esta lista.

Los comandos siguientes responden a las tres primeras sin cambiar nada. Lea cada resultado antes de continuar, porque cada respuesta descarta una reparación distinta.

uname -r
ls -l /lib/modules/$(uname -r)/build
modinfo wireguard
lsmod | grep wireguard

Si la segunda línea informa de que la ruta no existe, falta el entorno de compilación del kernel en ejecución y nada de lo que compile coincidirá con él. Si modinfo falla mientras la ruta existe, puede que el módulo no esté instalado en absoluto, lo cual es normal en kernels que incluyen la implementación en el árbol. Si modinfo tiene éxito y lsmod no muestra nada, el módulo existe pero no está cargado, lo que es un problema de carga y no de compilación. Cada resultado le lleva a un sitio distinto, por eso leer importa más que los comandos.

Compile contra la versión en ejecución

Un módulo externo se compila contra un árbol de kernel preparado, y la guía del kernel para módulos externos describe usar el directorio de compilación que pertenece al kernel en ejecución y no el que lleve el número de versión más alto. Ese directorio de compilación es un enlace simbólico mantenido por el paquete del kernel, así que apunta al árbol de la versión que está arrancada. La indirección es justamente el punto: elimina una elección que de otro modo haría mal. Nombrarlo explícitamente hace que el objetivo sea inequívoco.

Un detalle importa cuando el árbol solo se ha preparado y no se ha compilado del todo. El objetivo de preparación no genera el archivo de versionado de símbolos que necesitan algunas compilaciones externas, así que un árbol lleno de cabeceras no es automáticamente un entorno de compilación completo. Si una compilación falla por símbolos faltantes, ese archivo es el primer lugar donde mirar.

sudo make -C /lib/modules/$(uname -r)/build M=$(pwd) modules
sudo make -C /lib/modules/$(uname -r)/build M=$(pwd) modules_install
sudo depmod -a

Cuando las cabeceras empaquetadas van rezagadas

En distribuciones y ordenadores de una sola placa que empaquetan sus propios kernels, las cabeceras pueden ir días o semanas por detrás de la versión. El paquete de cabeceras puede ser correcto de nombre y más antiguo de contenido, lo que produce una compilación que compila y luego falla al cargar en lugar de durante la compilación. Mezclar fuentes lo empeora: un kernel de distribución con cabeceras de un repositorio de terceros, o un kernel de fabricante con cabeceras genéricas, puede compilar limpiamente y aun así ser rechazado por el kernel en ejecución porque la configuración difiere. Los números de versión por sí solos no lo resuelven.

Si la máquina sigue un canal de kernel experimental, decida a conciencia si quedarse allí con artefactos de compilación coincidentes o volver al conjunto de paquetes compatible. Repetir la actualización y esperar que las piezas encajen no es un plan, porque la misma discrepancia se reproduce cada vez.

Verifique la interfaz tras la reconstrucción

Tras una instalación correcta, crear la interfaz es la prueba que importa, seguida de leer qué cargó realmente el kernel y qué dice el registro si se negó. Un módulo que se carga y una interfaz que no se puede crear son fallos distintos con causas distintas. Los tres comandos siguientes los separan.

sudo ip link add wg9 type wireguard
lsmod | grep wireguard
sudo dmesg | tail -5

Si el módulo se niega a cargarse, el registro del kernel indica el motivo, y una discrepancia de versión es solo una de las posibilidades. Lea esa línea antes de reconstruir, porque una segunda compilación idéntica gasta los mismos diez minutos y produce la misma negativa. Después retire la interfaz temporal para que la siguiente prueba empiece desde un estado limpio.