Problema

En entornos de virtualización basados en Proxmox es frecuente conectar adaptadores de red USB de alta velocidad para ampliar la capacidad de ancho de banda sin abrir el chasis. Los modelos que usan el chipset Realtek RTL8159 (también conocidos como r8152) aparecen en el mercado como una opción económica para 10 GbE. Sin embargo, la mayoría de los kernels que incluye Proxmox no reconocen el hardware y no crean una interfaz en ip link. El síntoma típico es la ausencia de cualquier dispositivo enx* o eth* asociado al dongle, a pesar de que el bus USB lo detecta (lsusb muestra el ID 0bda:815a). El problema no es exclusivo de una versión concreta; cualquier nodo que ejecute un kernel sin el mapeo del ID de dispositivo sufrirá el mismo bloqueo.

Causa

El driver genérico r8152 que viene con el kernel Linux está preparado para varios chipsets Realtek, pero la tabla de IDs no incluye el identificador 0bda:815a usado por los adaptadores RTL8159/RTL8156B. Cuando el kernel intenta cargar r8152.ko no encuentra coincidencia y, como consecuencia, no registra ninguna interfaz de red. La causa raíz suele ser una de estas:

  1. Kernel desactualizado respecto al driver – Proxmox mantiene su propio árbol de headers y a veces se queda atrás de los últimos commits del driver upstream.
  2. Módulo empaquetado por Proxmox – El paquete realtek-r8152-dkms que a veces se incluye en repositorios de terceros no está alineado con la versión del kernel PVE.
  3. Actualizaciones automáticas del kernel – Después de una actualización, el módulo previamente compilado desaparece y el nuevo kernel vuelve a carecer del ID necesario.

En todos los casos, la solución pasa por proporcionar al kernel un módulo que sí reconozca el ID del dispositivo y que se recompila automáticamente cada vez que el kernel cambie.

Solución

La estrategia genérica consiste en compilar el driver oficial de Realtek desde su repositorio, instalarlo mediante DKMS y asegurarse de que el módulo personalizado tenga prioridad sobre cualquier versión incluida por Proxmox. Este enfoque funciona tanto en nodos recién instalados como en clusters con actualizaciones programadas.

Paso 1 – Preparar el entorno de compilación

Instale las herramientas de desarrollo y los headers exactos del kernel activo:

apt update
apt install -y build-essential dkms proxmox-headers-$(uname -r)

Paso 2 – Obtener el código fuente del driver

Descargue la versión oficial (v2.22.1 o superior) desde el sitio de Realtek o un espejo verificado y descomprímala en un directorio de trabajo:

mkdir -p ~/src && cd ~/src
tar xf /ruta/al/archivo/r8152-v2.22.1.tar.gz

Paso 3 – Compilar el módulo contra el kernel actual

cd r8152-v2.22.1
make KERNELDIR=/lib/modules/$(uname -r)/build

Al final debe aparecer r8152.ko en el directorio.

Paso 4 – Preparar el árbol DKMS

mkdir -p /usr/src/r8152-v2.22.1
cp -r * /usr/src/r8152-v2.22.1/

Cree el archivo de configuración dkms.conf:

cat > /usr/src/r8152-v2.22.1/dkms.conf <<'EOF'
PACKAGE_NAME="r8152"
PACKAGE_VERSION="v2.22.1"
BUILT_MODULE_NAME[0]="r8152"
DEST_MODULE_LOCATION[0]="/updates/dkms"
AUTOINSTALL="yes"
EOF

Paso 5 – Registrar, compilar e instalar vía DKMS

dkms add -m r8152 -v v2.22.1
dkms build -m r8152 -v v2.22.1
dkms install -m r8152 -v v2.22.1

DKMS guardará la compilación y la volverá a ejecutar automáticamente cuando el kernel cambie.

Paso 6 – Priorizar el módulo y actualizar initramfs

Proxmox incluye un módulo r8152 sin el ID necesario. Forzamos la carga del módulo DKMS y regeneramos la imagen de arranque:

echo "r8152" > /etc/modules-load.d/r8152.conf
update-initramfs -u -k all

Paso 7 – Limpiar versiones antiguas (opcional)

Si existían instalaciones previas de realtek-r8152 bajo otro nombre, elimínelas para evitar conflictos:

dkms remove -m realtek-r8152 -v 2.21.4 --all

Paso 8 – Reiniciar y validar

reboot

Al volver, ip link debe listar una interfaz enx… cuyo nombre corresponde a la MAC del dongle.

Cuándo aplicar esta solución

  • Síntomas: lsusb muestra el adaptador, pero ip link no muestra ninguna interfaz; dmesg contiene líneas como “r8152: unknown device 0bda:815a”.
  • Entorno: Proxmox VE (cualquier versión que use kernels personalizados) en servidores o estaciones de trabajo homelab.
  • Exclusiones: Si el adaptador ya funciona con el driver incluido en el kernel (por ejemplo, versiones más nuevas de Proxmox que ya incorporan el ID), no es necesario recompilar. También, si el nodo está bajo Secure Boot sin MOK enrolado, la firma del módulo DKMS puede fallar; en ese caso desactive Secure Boot o siga el proceso de enrolamiento.

Código

apt update && apt install -y build-essential dkms proxmox-headers-$(uname -r)

mkdir -p ~/src && cd ~/src
tar xf /ruta/al/archivo/r8152-v2.22.1.tar.gz
cd r8152-v2.22.1
make KERNELDIR=/lib/modules/$(uname -r)/build

mkdir -p /usr/src/r8152-v2.22.1
cp -r * /usr/src/r8152-v2.22.1/

cat > /usr/src/r8152-v2.22.1/dkms.conf <<'EOF'
PACKAGE_NAME="r8152"
PACKAGE_VERSION="v2.22.1"
BUILT_MODULE_NAME[0]="r8152"
DEST_MODULE_LOCATION[0]="/updates/dkms"
AUTOINSTALL="yes"
EOF

dkms add -m r8152 -v v2.22.1
dkms build -m r8152 -v v2.22.1
dkms install -m r8152 -v v2.22.1

echo "r8152" > /etc/modules-load.d/r8152.conf
update-initramfs -u -k all

dkms remove -m realtek-r8152 -v 2.21.4 --all || true

reboot

Verificación

  1. Comprobar módulo cargado

    lsmod | grep r8152

    Debería aparecer r8152 con la versión v2.22.1.

  2. Confirmar que la interfaz existe

    ip link show | grep enx

    El nombre será algo como enxf44dad0a4ce3.

  3. Validar el driver activo

    ethtool -i enxf44dad0a4ce3

    La salida debe contener driver: r8152 y version: v2.22.1.

  4. Prueba de rendimiento (opcional)

    iperf3 -s   # en el nodo receptor
iperf3 -c <IP_del_nodo> -P 4 -t 30

    Se esperan tasas entre 7 Gbps y 7.7 Gbps en enlaces USB‑3.2 Gen 2×1.

Notas adicionales

  • Pahole warning: Durante la compilación es normal ver una advertencia sobre la versión de pahole. No impide la generación del módulo, pero si desea eliminarla instale la versión exacta que usó el kernel (apt install pahole con la versión adecuada).
  • Secure Boot: Si el nodo tiene Secure Boot activado, DKMS firmará el módulo con la clave MOK del sistema. En caso de error, ejecute mokutil --import /var/lib/dkms/r8152/v2.22.1/…/signing_key.priv y siga el proceso de enrolamiento al reiniciar.
  • Actualizaciones de Proxmox: Cada vez que el kernel cambie, DKMS recompilará automáticamente el driver. No es necesario volver a ejecutar los pasos de compilación, solo asegúrese de que dkms status muestre “installed” para la nueva versión del kernel.
  • Compatibilidad con RTL8156B: El mismo driver cubre también el chipset RTL8156B (2.5 GbE). Si el adaptador es de esa familia, los mismos pasos aplican sin cambios.