🛠️ Realtek 2.5GbE (RTL8125) Link Flapping & DKMS Driver Fix Runbook

This runbook documents the root cause, troubleshooting steps, and permanent solution for physical Ethernet link flapping, high packet loss, and delayed node availability on Proxmox VE hosts equipped with Realtek 2.5GbE (RTL8125 / RTL8125B / RTL8125BG) network controllers.

---

🚨 Problem Description & Symptoms

Symptoms

1. High Packet Loss / Unstable Ping: Pinging the node returns sporadic responses with 90%+ packet loss (Request time-out, Sendto: Host is down).
2. Delayed Availability on Boot: Even after the Proxmox console login prompt appears on physical display, the node remains unreachable via Web GUI and SSH for 30–90+ seconds.
3. Console Log Spam:

   [ 32.254913] r8169 0000:02:00.0 nic1: Link is Up - 2.5Gbps/Full - flow control rx/tx
   [ 32.255006] vmbr0: port 1(nic1) entered blocking state
   [ 32.255006] vmbr0: port 1(nic1) entered forwarding state
   [ 34.032447] r8169 0000:02:00.0 nic1: Link is Down
   [ 34.032541] vmbr0: port 1(nic1) entered disabled state
   [ 37.067985] r8169 0000:02:00.0 nic1: Link is Up - 2.5Gbps/Full
   [ 38.067310] r8169 0000:02:00.0 nic1: Link is Down
   [ 73.919124] r8169 0000:02:00.0 nic1: Link is Down
   [ 76.961249] r8169 0000:02:00.0 nic1: Link is Up - 2.5Gbps/Full

Root Cause

The default in-tree Linux kernel driver r8169 does not handle power-saving states and link negotiation cleanly on Realtek RTL8125 2.5GbE hardware. Specifically:

• Energy Efficient Ethernet (EEE) causes the PHY link to enter low-power sleep and drop carrier sync.
• PCIe Active State Power Management (ASPM) puts the PCIe bus controller into low-power states, causing repeated link renegotiation cycles.
• Generic In-Tree Module: The generic r8169 driver lacks chip-specific workarounds present in Realtek's official standalone r8125 driver.

---

🛠️ Step-by-Step Resolution

Step 1: Disable Energy Efficient Ethernet (EEE)

Persistently disable EEE on the interface so the PHY stays active at full power.

1. Edit /etc/network/interfaces:

   nano /etc/network/interfaces

2. Add post-up /sbin/ethtool --set-eee nic1 eee off directly under iface nic1 inet manual:

   iface nic1 inet manual
           post-up /sbin/ethtool --set-eee nic1 eee off

---

Step 2: Disable PCIe ASPM Power Saving (for systemd-boot)

IMPORTANT

Proxmox VE hosts booting via UEFI/ZFS utilize systemd-boot via proxmox-boot-tool, NOT standard GRUB. Modifying /etc/default/grub will NOT pass kernel parameters. You must modify /etc/kernel/cmdline.

1. Check current kernel command line:

   cat /etc/kernel/cmdline

2. Edit /etc/kernel/cmdline and append pcie_aspm=off to the end of the single line:

   root=ZFS=rpool/ROOT/pve-1 boot=zfs intel_idle.max_cstate=1 processor.max_cstate=1 pcie_aspm=off

3. Sync changes across all boot ESP partitions:

   proxmox-boot-tool refresh

---

Step 3: Enable Debian non-free Repositories & Install r8125-dkms

Proxmox 8 / 9 and Debian 12 / 13 (Trixie) store repository configs in /etc/apt/sources.list.d/debian.sources.

1. Add contrib, non-free, and non-free-firmware to APT components:

   sed -i 's/Components: main/Components: main contrib non-free non-free-firmware/g' /etc/apt/sources.list.d/debian.sources

2. Refresh package cache:

   apt update

3. Install DKMS build tools, Proxmox kernel headers, and the official Realtek driver:

   apt install -y proxmox-default-headers dkms r8125-dkms

4. Verify DKMS built the module successfully:

   dkms status

   Expected output: r8125/<version>, <kernel-version>, x86_64: installed

---

Step 4: Blacklist Old r8169 & Update Initramfs

By default, the initial RAM disk (initramfs) caches the old r8169 driver and loads it before root filesystem rules take effect. You must blacklist r8169, force-load r8125, and rebuild initramfs.

1. Blacklist r8169:

   echo "blacklist r8169" > /etc/modprobe.d/blacklist-r8169.conf

2. Force load r8125 at boot:

   echo "r8125" > /etc/modules-load.d/r8125.conf

3. Rebuild initramfs for all installed kernels:

   update-initramfs -u -k all

4. Refresh bootloader:

   proxmox-boot-tool refresh

5. Reboot the node:

   reboot

---

🔍 Verification & Health Check

After the system reboots, run the following verification checks:

1. Verify Active Driver Module

lspci -nnk -d 10ec:

Expected Output:

02:00.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller [10ec:8125] (rev 05)
        Subsystem: Realtek Semiconductor Co., Ltd. Device [10ec:0123]
        Kernel driver in use: r8125
        Kernel modules: r8169, r8125

(Confirms Kernel driver in use: r8125).

2. Verify Kernel Parameters

cat /proc/cmdline

(Must contain pcie_aspm=off).

3. Verify EEE Status

ethtool --show-eee nic1

(Must report EEE status: disabled).

4. Verify dmesg Link Stability

dmesg | grep -iE "r8125|nic1|vmbr0"

(Should show a single initial link-up at 2.5Gbps with zero link-down events afterwards).

---

🔗 Related Documentation

• Cluster Network Architecture & Dual-NIC Bonding
• Cluster Nodes & Topology
• Documentation Guidelines