Fj Graf

Guide: Installing Realtek RTL8125 Driver on Debian/Proxmox

Written by

fjgraf

in

This guide resolves issues encountered when installing the TP-Link TX21/Realtek RTL8125 driver on a Debian-based system (like Proxmox) that already has an older Realtek NIC using the built-in r8169 driver.

Prerequisites

  • Console Access: Since network connectivity will be interrupted, you must have physical access (keyboard/monitor) or IPMI/iDRAC/vPro access.
  • Latest Driver: Ensure you download the latest Linux driver tarball for the RTL8125 chip directly from the Realtek website to avoid compilation errors with newer kernels.
  • Kernel Headers & DKMS: Install the necessary packages for compiling the driver:Bash
apt update
apt install build-essential dkms pve-headers

1. Resolve Driver Installation Failure (The Hang)

The installer (autorun.sh) will hang because the kernel’s default r8169 driver is actively in use by another NIC.

A. Identify and Disable the Conflicting Interface

  1. Find the Physical Interface and Bridge: Use ip a to identify the active interface using the r8169 driver (e.g., enp6s0) and the corresponding Proxmox bridge (e.g., vmbr1).
  2. Bring Down the Network: This will stop the driver’s process, allowing the installer to unload it.
ifdown vmbr1               # Bring down the bridge (crucial for Proxmox)
ip link set enp6s0 down    # Bring down the physical interface
  • Manually Unload the Old Driver:
rmmod r8169

B. Run the Installation

  1. Navigate to the new driver directory (e.g., cd r8125-9.011.00).
  2. Execute the installer:
./autorun.sh

If successful, the script will compile the new r8125 module using DKMS and install it.

Reboot:

reboot

2. Resolve NIC Conflict (Missing Interfaces)

After installation, the new r8125 driver often aggressively claims both the new NIC and the older onboard NIC, leaving the older one unusable.

The solution is to bind the custom r8125 driver only to the new card, leaving the old card for the kernel’s r8169 driver.

A. Identify the New Card’s PCI Address

  1. List PCI devices and find the new Realtek card: Look for the device actively using the r8125 driver and note its PCI address (e.g., 04:00.0).
lspci -nnk | grep -i realtek -A3

B. Create a Driver Binding Rule

  1. Create the configuration file: This uses the install directive to tell the system to load r8125 but only bind it to the specified PCI address.
# REPLACE [NEW_CARD_PCI_ADDRESS] with your actual address (e.g., 04:00.0)
echo 'install r8125 /sbin/modprobe --ignore-install r8125; /usr/bin/echo "[NEW_CARD_PCI_ADDRESS]" > /sys/bus/pci/drivers/r8125/bind' > /etc/modprobe.d/r8125-bind.conf
  • Update Initramfs: This applies the new binding rule before the kernel loads drivers.
update-initramfs -u -k all

and reboot now.

3. Final Verification

After the final reboot, both network interfaces should be present and active:

  • Check all interfaces:Bash
ip a
  • Verify drivers:
    • The new TX21 card should show driver: r8125.
    • The old onboard NIC (e.g., enp6s0) should show driver: r8169.

More posts