Proxmox 8 / Debian 12 with Realtek RTL8111H NIC

TL;DR A default Proxmox 8 / Debian 12 install uses the wrong module for the RTL8111H – we need to build & install the correct module

I came across this problem using Proxmox on the Asrock J4125-ITX / J5040-ITX / N100 series boards. These are great boards to run a low-power mini server, they run Proxmox really very well, but a default install will leave you thinking the onboard NIC is faulty. Here’s why.

The Realtek RTL8111H NIC used on the Asrock boards is a cheap but capable Gigabit Ethernet (10/100/1000M) PCI Express device. Now I’ve used boards with on-board Realtek NICs for years without incident on Windows machines, but turns out Linux support for some of these chipsets is sub-optimal.

So you’ve done a default install of Proxmox. Your network is up, you have an IP, everything’s working, right? Wrong!

lspci -nnv

02:00.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL8111/8168/8411 PCI Express Gigabit Ethernet Controller [10ec:8168] (rev 15)
...
Kernel driver in use: r8169
Kernel modules: r8169

When we take a look at the RealTek website, we can see that the R8169 is part of a family of Realtek NICs sharing the same driver:
RTL8110S/RTL8169S/RTL8110SB/RTL8169SB/RTL8110SC/RTL8169SC

Now we know that our board is, in fact, sporting an RTL8111H, which isn’t in that list.

A little sleuthing and we can find a similar, but different family containing:
RTL8111B/RTL8111C/RTL8111D/RTL8111E/RTL8111F/RTL8111G(S)/RTL8111H(S)//RTL8118(A)(S)/RTL8119i/RTL8111L/RTL8111K
RTL8168B/RTL8168E/RTL8168H
RTL8111DP/RTL8111EP/RTL8111FP
RTL8411/RTL8411B

There’s another clue on that page in the driver name: GBE Ethernet LINUX driver r8168 … So Linux has chosen the wrong kernel module to support this hardware. It sort-of works, because the hardware is kinda similar, which is hella confusing, but you’ll run into all sorts of nasty behaviour if you don’t fix it.

RealTek supply a drivers for kernel up to v6.8, Proxmox 8 currently uses 6.8.8-4-pve and it’s working fine. Go ahead, download the file (behind a captcha, so you’ll need to use a browser):

GBE Ethernet LINUX driver r8168 for kernel up to 6.8, v8.053.00, 2024/04/18
https://www.realtek.com/Download/List?cate_id=584

You should get a file named r8168-8.053.00.tar.bz2. Copy it to /tmp on the Proxmox / Debian box (I used scp for this, if you’re coming from a Windows box WinSCP is a great option).

If you’ve just installed Proxmox and you don’t have a subscription, you’ll need to change to the free repositories. Don’t do this if you do have a subscription – instead enter your key in the Proxmox UI to enable the enterprise repositories.

echo "deb http://download.proxmox.com/debian/ceph-quincy bookworm no-subscription" > /etc/apt/sources.list.d/ceph.list
echo "deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription" > /etc/apt/sources.list.d/pve-enterprise.list

Do a quick update and install headers and build essentials

apt update
apt upgrade
apt install pve-headers build-essential

Next let’s extract the driver package

cd /tmp
tar xf r8168-8.053.00.tar.bz2
cd r8168-8.053.00/

Let’s check the module compiles OK:

make modules

If everything goes right you should get the following with no major errors:

make -C src/ modules
make[1]: Entering directory '/tmp/r8168-8.053.00/src'
make -C /lib/modules/6.8.8-4-pve/build M=/tmp/r8168-8.053.00/src modules
make[2]: Entering directory '/usr/src/linux-headers-6.8.8-4-pve'
CC [M] /tmp/r8168-8.053.00/src/r8168_n.o
CC [M] /tmp/r8168-8.053.00/src/r8168_asf.o
CC [M] /tmp/r8168-8.053.00/src/rtl_eeprom.o
CC [M] /tmp/r8168-8.053.00/src/rtltool.o
LD [M] /tmp/r8168-8.053.00/src/r8168.o
MODPOST /tmp/r8168-8.053.00/src/Module.symvers
CC [M] /tmp/r8168-8.053.00/src/r8168.mod.o
LD [M] /tmp/r8168-8.053.00/src/r8168.ko
BTF [M] /tmp/r8168-8.053.00/src/r8168.ko
Skipping BTF generation for /tmp/r8168-8.053.00/src/r8168.ko due to unavailability of vmlinux
make[2]: Leaving directory '/usr/src/linux-headers-6.8.8-4-pve'
make[1]: Leaving directory '/tmp/r8168-8.053.00/src'

If all looks good, we can run the convenience script from RealTek that will unload the r8169 module and install the newly compiled one in its place.

For the next step you will want to be on a physical console or IP KVM on the box … you’re going to be replacing the network card driver, which will drop connectivity, so don’t try to do this over an SSH connection (unless you’ve installed a second NIC for the purpose)!

chmod 755 autorun.sh
./autorun.sh

Check old driver and unload it.
rmmod r8169
Build the module and install
Skipping BTF generation for /tmp/r8168-8.053.00/src/r8168.ko due to unavailability of vmlinux
Warning: modules_install: missing 'System.map' file. Skipping depmod.
Backup r8169.ko
rename r8169.ko to r8169.bak
DEPMOD 6.8.8-4-pve
load module r8168
Updating initramfs. Please wait.
update-initramfs: Generating /boot/initrd.img-6.8.8-4-pve
Running hook script 'zz-proxmox-boot'..
Re-executing '/etc/kernel/postinst.d/zz-proxmox-boot' in new private mount namespace..
No /etc/kernel/proxmox-boot-uuids found, skipping ESP sync.
Completed.

For good measure let’s blacklist the r8169 module to prevent future problems:

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

Final check with lspci:

lspci -nnv

03:00.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL8111/8168/8411 PCI Express Gigabit Ethernet Controller [10ec:8168] (rev 15)
...
Kernel driver in use: r8168
Kernel modules: r8168

Nice!

Now reboot your box and make sure everything works as it should.

If you can’t ping etc from the box, check the interface name of the RealTek NIC, it might have changed and you might need to update the bridge-port name for vmbr0

ip a

....
2: eno1: mtu 1500 qdisc pfifo_fast master vmbr0 state UP group default qlen 1000
....

nano /etc/network/interfaces

auto lo
iface lo inet loopback

iface eno1 inet manual

auto vmbr0
iface vmbr0 inet static
  address x.x.x.x/24
  gateway x.x.x.x
  bridge-ports eno1
  bridge-stp off
  bridge-fd 0

That’s it! Enjoy your swanky Proxmox box to the full!