This blog post was created because my driver was missing for the Framework Desktops Ethernet driver. If you have the same setup and want to reach the same goal, you can almost blindly copy and paste everything.
Building your TrueNas Scale kernel
For building you need an OS that is almost identical for your truenas. I used in my tests Debian 12 devcontainer because it was already close enough.
Copy the current kernel config
cp /boot/config-$(uname -r) .config
That is the config that contains all the compiler flags that where used in your build of truenas scale.
Clone the kernel source
git clone https://github.com/truenas/linux.git
cd linux
Now checkout the correct version that matches your running kernel.
The version are oganized by tags with the name schema:
TS-XX.YY.Z
Where XX.YY.Z is the version of your TrueNas Scale installation.
So in my case my tag is TS-24.10.1
git checkout TS-24.10.1
Prepare the build environment
Install missing tools
apt update && apt install -y \
build-essential \
linux-headers-6.6.44-rt \
dkms \
git \
curl \
wget \
pciutils \
net-tools \
iproute2 \
systemd
Copy the config file
cp ../.config .config
Disable signed builds because we don't have the keys to sign the modules
scripts/config --disable CONFIG_SYSTEM_TRUSTED_KEYS
scripts/config --disable CONFIG_MODULE_SIG_KEY
scripts/config --disable CONFIG_SYSTEM_REVOCATION_KEYS
Build the module
make olddefconfig
make modules_prepare
make -j $(nproc) modules
To check if the build was successful, check if in the root of the linux folder now a file exists with the name
Module.symvers
To fix errors you can try to run
make -j1 modules. It will take way longer because it limits the build to use only a single core.
Build the driver sysext
You can download the latest driver from here
cd .. * go back to the root folder
wget -O r8126-driver.tar.bz2 https://...your dowload uri...
tar -xjf r8126-driver.tar.bz2
cd r8126-*/src/ # change to the extracted folder
Run the build and point to your custom linux kernel:
make -C ../../linux M=$(pwd) modules
After that in the current folder a file named r8126.ko should exist.
Now create the folder structure for the sysext:
mkdir -p ../build/r8126-sysext/usr/lib/modules/6.6.44-production+truenas/extra
mkdir -p ../build/r8126-sysext/usr/lib/extension-release.d
This can be copied into the build folder structure that already exists next to this readme file:
cp r8126.ko ../build/r8126-sysext/usr/lib/modules/6.6.44-production+truenas/extra/r8126.ko
After that check on you installed truenas the data that is returned by the command:
cat /etc/os-release
And create a file with the name extension-release.r8126-sysext in the folder build/r8126-sysext/usr/lib/extension-release.d/ with the following content:
ID=debian
VERSION_ID=12
SYSEXT_LEVEL=1
Modify the file if needed, for your os release data.
Now create the sysext file:
mksquashfs r8126-sysext r8126-sysext.raw -noappend -comp xz
Now you have the r8126-sysext.raw file that can be used to install the driver into TrueNas Scale.
Install
Important: All commands need to run as root. Without root they are maybe not available or will fail.
Create a pool that will survive system updates:
zfs create boot-pool/customsysext
Mount the custom sysext dataset:
zfs set mountpoint=/root/customsysext boot-pool/customsysext
Copy your custom sysext to the extensions folder
cp /mnt/usbdrive/r8126-sysext.raw /root/customsysext/
Copy for now the custom module to the extensions folder:
mkdir -p /var/lib/extensions/
cp /root/customsysext/r8126-sysext.raw /var/lib/extensions/
Refresh the system extensions:
systemd-sysext refresh
Install the driver:
insmod /usr/lib/modules/$(uname -r)/extra/r8126.ko
Now you should have temporary network access until the next reboot.
Go to the webui and create a init script.
The script should contain the following line:
zfs set mountpoint=/root/customsysext boot-pool/customsysext && mkdir -p /var/lib/extensions/ && cp /root/customsysext/r8126-sysext.raw /var/lib/extensions/ && systemd-sysext refresh && insmod /usr/lib/modules/$(uname -r)/extra/r8126.ko
This will mount the pool in where our customization lives. Then it will copy everything and will install the driver.