RTL8126 Offline Installer

Offline driver installer for Realtek RTL8126 5GbE on Ubuntu 24.04 LTS
No internet required — just a USB stick.

---

The Problem

Ubuntu 24.04 Server (kernel 6.8) ships without a driver for the Realtek RTL8126 5GbE NIC. To compile the driver you need build-essential, linux-headers, dkms… but you can't install those without a network connection.

This project solves that chicken-and-egg problem.

How It Works

Script	Where	What it does
prepare.sh	Machine with internet	Downloads ~136 .deb packages + Realtek driver source
install.sh	Target server (offline)	Installs everything from USB with multiple fallback strategies

install.sh features

• 4-pass dpkg with dependency resolution (fully non-interactive)
• 4 driver install methods in cascade: DKMS → autorun.sh → make → broad search
• Automatic Ethernet activation with DHCP (dhclient → networkctl → dhcpcd)
• WiFi fallback if Ethernet fails (wpa_supplicant with 3 driver backends)
• Blacklists r8169 to prevent driver conflicts
• Persists everything: Netplan, modules-load.d, initramfs, systemd services
• Full debug dump saved to log file on USB stick
• Zero interactive prompts — runs unattended

Quick Start

1. Prepare the USB stick

On a machine with internet access:

git clone https://github.com/ayinedjimi/rtl8126-ubuntu-offline.git
cd rtl8126-ubuntu-offline

./prepare.sh                            # on Ubuntu 24.04
# or
./prepare.sh --docker                   # on any OS with Docker
# or
./prepare.sh --kernel 6.8.0-51-generic  # specific kernel version

Then copy the output to your USB stick:

cp -r build/* /media/your-usb/

2. Install on the server

sudo mkdir -p /mnt/usb
lsblk                              # find your USB device (e.g. sdb1)
sudo mount /dev/sdb1 /mnt/usb

sudo bash /mnt/usb/install.sh

The script will display a step-by-step progress report and a final summary.

WiFi Fallback

If no Ethernet cable is detected, the installer will attempt to connect via WiFi. Edit install.sh before copying to USB:

WIFI_SSID="YourNetwork"
WIFI_PASS="YourPassword"

Supported Configurations

Ubuntu	Kernel	Arch	Status
24.04 LTS	6.8.0-100-generic	amd64	Tested
24.04 LTS	6.8.0-*	amd64	Should work
24.04.2+ LTS	6.11+	amd64	Untested (different headers)

Note: prepare.sh downloads headers for a specific kernel version. Make sure it matches the kernel on your target server (uname -r).

Project Structure

rtl8126-ubuntu-offline/
├── prepare.sh          # Downloads packages + driver (run with internet)
├── install.sh          # Offline installer (run on target server)
├── LICENSE
├── README.md
└── build/              # Created by prepare.sh (git-ignored)
    ├── install.sh
    ├── debs/           # ~136 .deb packages (~430 MB)
    └── r8126-*/        # Realtek driver source

Troubleshooting

The installer writes a detailed log file on the USB stick (install-*.log). It includes: dmesg, lspci -k, lsmod, modinfo, dkms status, ip link, and more.

Problem	Solution
Script hangs at "Passe 1/4"	Older version without DEBIAN_FRONTEND=noninteractive. Re-download.
Module r8126 not loaded	Check dmesg | grep r8126 — verify linux-headers match uname -r
r8169 conflict	Installer blacklists it automatically. Manual: sudo rmmod r8169 && sudo modprobe r8126
No WiFi interface found	Your WiFi card may need a separate driver
DHCP timeout	Try manual: sudo ip addr add 192.168.1.100/24 dev ethX

Credits

• Realtek r8126 driver
• realtek-r8126-dkms by awesometic
• Built with Claude Code

License

Scripts are MIT licensed. The Realtek driver is subject to Realtek's license terms.